{"id":49815510,"url":"https://github.com/zhikunqingtao/zhikuncode","last_synced_at":"2026-05-29T21:00:59.546Z","repository":{"id":352986310,"uuid":"1202436319","full_name":"zhikunqingtao/zhikuncode","owner":"zhikunqingtao","description":"Claude Code 的开源替代方案。Multi Agent AI 编程助手，CLI \u0026 Web UI 双入口。自托管，随处部署——手机浏览器也能完整操控。支持任意 LLM，原生浏览器自动化，90+ 命令。技能、插件与持久记忆。企业级安全，零锁定。Docker 一键部署。","archived":false,"fork":false,"pushed_at":"2026-05-24T14:00:01.000Z","size":149428,"stargazers_count":243,"open_issues_count":22,"forks_count":73,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T16:03:26.438Z","etag":null,"topics":["ai-coding-assistant","chinese-llm","docker","llm","multi-agent","open-source","self-hosted","web-ui"],"latest_commit_sha":null,"homepage":"https://zhikunqingtao.github.io/zhikuncode/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhikunqingtao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T02:50:27.000Z","updated_at":"2026-05-24T14:00:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"488948ea-2203-41ce-8a01-6141270fc2f4","html_url":"https://github.com/zhikunqingtao/zhikuncode","commit_stats":null,"previous_names":["zhikunqingtao/zhikuncode"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zhikunqingtao/zhikuncode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhikunqingtao%2Fzhikuncode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhikunqingtao%2Fzhikuncode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhikunqingtao%2Fzhikuncode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhikunqingtao%2Fzhikuncode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhikunqingtao","download_url":"https://codeload.github.com/zhikunqingtao/zhikuncode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhikunqingtao%2Fzhikuncode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33670211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding-assistant","chinese-llm","docker","llm","multi-agent","open-source","self-hosted","web-ui"],"created_at":"2026-05-13T06:00:43.984Z","updated_at":"2026-05-29T21:00:59.535Z","avatar_url":"https://github.com/zhikunqingtao.png","language":"Java","funding_links":[],"categories":["人工智能"],"sub_categories":["AI智能体"],"readme":"[🌐 English](docs/README_EN.md)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"ZhikunCode\" width=\"120\" /\u003e\n  \u003ch1\u003eZhikunCode\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003e开源 AI 编程助手 — 部署一次，浏览器全流程操控\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e多 Agent 协作 · Docker 自托管 · 国产大模型直连 · 深度安全架构\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"#-快速开始\"\u003e快速开始\u003c/a\u003e ·\n    \u003ca href=\"#-特性亮点\"\u003e核心特性\u003c/a\u003e ·\n    \u003ca href=\"#-demo\"\u003e在线演示\u003c/a\u003e ·\n    \u003ca href=\"#-swe-bench-lite-评测\"\u003eSWE-bench 评测\u003c/a\u003e ·\n    \u003ca href=\"#-cli-工具\"\u003eCLI 工具\u003c/a\u003e ·\n    \u003ca href=\"#-skill技能系统\"\u003eskill技能系统\u003c/a\u003e ·\n    \u003ca href=\"#-插件系统\"\u003e插件系统\u003c/a\u003e ·\n    \u003ca href=\"#-可视化\"\u003e可视化\u003c/a\u003e ·\n    \u003ca href=\"#-记忆系统\"\u003e记忆系统\u003c/a\u003e ·\n    \u003ca href=\"#-竞品对比\"\u003e竞品对比\u003c/a\u003e ·\n    \u003ca href=\"docs/README_EN.md\"\u003eEnglish\u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/zhikunqingtao/zhikuncode\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docker-Ready-blue?logo=docker\" alt=\"Docker\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/zhikunqingtao/zhikuncode/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/zhikunqingtao/zhikuncode?style=social\" alt=\"GitHub Stars\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/zhikunqingtao/zhikuncode\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/zhikunqingtao/zhikuncode\" alt=\"Last Commit\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/zhikunqingtao/zhikuncode\"\u003e\u003cimg src=\"https://img.shields.io/github/languages/code-size/zhikunqingtao/zhikuncode\" alt=\"Code Size\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/zhikunqingtao/zhikuncode/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/zhikunqingtao/zhikuncode/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html\"\u003e\u003cimg src=\"https://img.shields.io/badge/SWE--bench%20Lite-46.3%25%20(139%2F300)-7a2410?logo=python\u0026logoColor=white\" alt=\"SWE-bench Lite 46.3% (139/300)\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n\u003e **部署到服务器，打开浏览器就能用，手机上也行**\n\n\u003e 🏗️ **[查看完整系统架构图 →](https://zhikunqingtao.github.io/zhikuncode/ZhikunCode-Architecture.html)**  \n\u003e 三端分离 · 837 文件 · 109,548 行代码（含测试 137,169 行）· 全景可视化\n\n\u003e 🏆 **[SWE-bench Lite 技术报告 →](https://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html)**  \n\u003e 提交命名空间 `20260520_zhikuncode` · 官方 harness 评测 Resolve **139 / 300 (46.3%)** · Patch 生成率 280 / 300 (93.3%)\n\n---\n\n## ✨ 特性亮点\n\n| | 特性 | 说明 |\n|---|---|---|\n| 🌐 | **浏览器全流程操控** | 部署一次，任何设备的浏览器即可完成全流程操作 —— 权限审批、方案协商、任务管控，手机上也能用，无需安装客户端 |\n| 🤖 | **多 Agent 协作** | Team（固定分工）/ Swarm（动态协商）/ SubAgent（主从委派）三种协作模式，复杂任务自动分工 |\n| 🔒 | **深度安全架构** | 8 层 Bash 沙箱(错误分类+输出截断+进程树管理) + 14 步权限管道 + 308 项安全测试覆盖（含 v9.3 新增 19 个 CWE-22 深度防御单测），命令执行前必过安全关卡 |\n| 🇨🇳 | **国产大模型直连** | 千问 / DeepSeek / Moonshot 开箱即用，国内网络直连，无需科学上网 |\n| 🐳 | **Docker 一键部署** | `docker compose up -d` 一条命令启动，数据存本地，完全私有 |\n| ⚡ | **智能上下文管理** | 五层压缩级联 + 增量折叠（每10轮自动压缩）+ 413三阶段恢复（激进压缩→反应式压缩→媒体剥离）+ 精确 Token 计数（tiktoken 多模型支持）+ 自纠错循环（编译/测试失败自动诊断修复，最多3次）+ Token三级告警，无缝应对超长对话 |\n| 🖼️ | **浏览器语义快照** | `/snap` 命令智能捕获网页完整状态（DOM 结构 + 交互元素），支持富交互页面语义提取，生成结构化 JSON 供 Agent 解析和回放验证 |\n| 📊 | **实时活动追踪与审批** | Activity Panel 实时记录 AI 工具执行全流程，L1/L2/L3 三层展示体系，Signal 智能标记（auto_approve/review_recommended/needs_review），一键批量审批决策，SQLite 后端持久化，支持会话恢复 |\n| 🏆 | **SWE-bench Lite 实测** | 单模型 `qwen-3.6-max-preview` + 6 工具闭集（Read/Edit/Write/Bash/Grep/Glob），无网络、无 sub-agent；官方 harness 评测 **Resolve 46.3% (139/300)**、Patch 生成率 **93.3% (280/300)**，[技术报告 →](https://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html) |\n\n---\n\n## 🎬 Demo\n\n### 📱 手机开发前后端 TODO 应用完整演示\n\nhttps://github.com/user-attachments/assets/bf1f1d3a-4a9b-4d91-af48-97a7d3dd7b8a\n\n### 自动写代码下载小红书视频\n\nhttps://github.com/user-attachments/assets/4b66261b-3258-44bd-82d3-6b2b3bbd4995\n\n![自动写代码下载小红书视频](docs/assets/demo-auto-code-xiaohongshu.gif)\n\n### 📱 项目分析和命令执行演示\n\nhttps://github.com/user-attachments/assets/7b45c5d4-e540-4ffd-80d4-e11502477dba\n\n### 文件操作\n![文件操作演示](docs/assets/demo-file-operation.gif)\n\n### 生成游戏\n![生成游戏演示](docs/assets/demo-game-generation.gif)\n\n### 优化代码\n![优化代码演示](docs/assets/demo-code-optimization.gif)\n\n### 多 Agent 协作开发前后端应用\n![多 Agent 协作演示](docs/assets/demo-multi-agent-todo.gif)\n\n### iPad 浏览器全流程操控\n![iPad浏览器操控演示](docs/assets/demo-ipad-browser.gif)\n\n---\n\n## ⚡ 快速开始\n\n### 前置准备：获取 LLM API Key\n\n本项目需要 LLM（大语言模型）API Key 才能运行。默认使用**阿里云千问（DashScope）**，国内网络直连。\n\n**获取千问 API Key：**\n1. 访问 [阿里云百炼平台 API Key 管理](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/api-key)\n2. 注册或登录阿里云账号\n3. 创建 API Key，复制完整密钥（以 `sk-` 开头）\n\n\u003e 千问提供免费额度，足够个人开发使用。也可以使用 [DeepSeek](https://platform.deepseek.com/)、[Moonshot/Kimi](https://platform.moonshot.cn/) 等国内服务商，详见下方\"支持的 LLM 服务商\"。\n\n### 方式一：Docker 部署（推荐）\n\n只需 3 步，从零到可用：\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/zhikunqingtao/zhikuncode.git\ncd zhikuncode\n\n# 2. 配置 API Key\ncp .env.example .env\n# 编辑 .env，填入你的 LLM API Key（默认使用千问/DashScope，国内直连）\n\n# 3. 启动\ndocker compose up -d\n```\n\n\u003e **首次构建说明：** 第一次运行会自动构建 Docker 镜像，需要下载依赖并编译，预计耗时 **15-30 分钟**（取决于网络速度）。后续启动只需几秒。可通过 `docker compose logs -f` 查看构建进度。\n\n启动完成后，打开浏览器访问 **http://localhost:8080** 即可使用。\n\n\u003e **系统要求：** Docker 20.10+，Docker Compose V2，建议 4GB+ 内存。\n\n### 方式二：本地开发\n\n**前置条件：** JDK 21、Node.js 22+、Python 3.11~3.12（不支持 3.13+）\n\n```bash\ngit clone https://github.com/zhikunqingtao/zhikuncode.git\ncd zhikuncode\n\n# 配置环境变量\ncp .env.example .env\n# 编辑 .env，填入你的 LLM API Key\n\n# 一键启动三端服务\n./start.sh\n```\n\n三端服务会同时启动：\n\n| 服务 | 地址 | 说明 |\n|------|------|------|\n| **Backend** | `http://localhost:8080` | Java Spring Boot 后端，核心 API |\n| **Python Service** | `http://localhost:8000` | FastAPI 服务，代码分析 |\n| **Frontend** | `http://localhost:5173` | React 开发服务器 |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e手动分别启动各服务\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# 后端\ncd backend \u0026\u0026 ./mvnw spring-boot:run -DskipTests\n\n# Python 服务\ncd python-service\npython -m venv venv \u0026\u0026 source venv/bin/activate\npip install -r requirements.txt\nuvicorn src.main:app --host 0.0.0.0 --port 8000\n\n# 前端\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n\u003c/details\u003e\n\n### 支持的 LLM 服务商\n\nZhikunCode 支持**多 Provider 同时配置**（推荐）和单 Provider 两种模式。多 Provider 模式下可在前端自由切换模型：\n\n**方式一：多 Provider 配置（推荐）**\n\n在 `.env` 中为每个服务商配置独立的 API Key，前端可自由切换：\n\n```bash\n# DashScope（千问系列）\nLLM_PROVIDER_DASHSCOPE_API_KEY=your-dashscope-key\n\n# DeepSeek\nLLM_PROVIDER_DEEPSEEK_API_KEY=your-deepseek-key\n\n# Moonshot (Kimi)\nLLM_PROVIDER_MOONSHOT_API_KEY=your-moonshot-key\n```\n\n**方式二：单 Provider 配置（向后兼容）**\n\n如未配置多 Provider，系统自动回退到单 Provider 模式。在 `.env` 中配置 `LLM_BASE_URL` 和 `LLM_API_KEY` 即可切换：\n\n| 服务商 | Base URL | 推荐模型 | 备注 |\n|--------|----------|----------|------|\n| **千问/DashScope** | `https://dashscope.aliyuncs.com/compatible-mode/v1` | qwen3.7-max | **默认**，国内直连 |\n| **DeepSeek** | `https://api.deepseek.com/v1` | deepseek-v4-pro | 国内直连 |\n| **Moonshot（Kimi）** | `https://api.moonshot.cn/v1` | kimi-k2.6 | 国内直连 |\n| **OpenAI** | `https://api.openai.com/v1` | gpt-4o | 需要外网访问 |\n| **本地 Ollama** | `http://localhost:11434/v1` | qwen2.5:latest | 完全离线 |\n\n\u003e 任何兼容 OpenAI API 格式的服务商都可以接入，只需配置对应的 Base URL 和 API Key。\n\n### 可选：启用 DashScope 托管 MCP 服务\n\n从最新版本起，为避免未配置阿里云百炼 Key 的用户遭遇启动日志刷屏，**默认不启用**以下托管在 `dashscope.aliyuncs.com` 上的 MCP 服务：\n\n| MCP 服务 | 能力 | 对应工具 ID |\n|---------|------|-------------|\n| `Wan25Media` | 万相 2.5 图像生成 / 图生图 | `mcp_wan25_image_gen`、`mcp_wan25_image_edit` |\n| `zhipu-websearch` | 智谱联网搜索 Pro | `mcp_web_search_pro` |\n\n\u003e ℹ️ 不启用这些 MCP 完全不影响核心对话、代码编辑、本地工具使用。\n\n**如需使用**（需要阿里云百炼 API Key 且在控制台开通相应 MCP 能力）：\n\n1. 在 `.env` 中配置 DashScope Key：\n   ```bash\n   LLM_PROVIDER_DASHSCOPE_API_KEY=sk-xxxxxxxx\n   ```\n2. 在 [`backend/src/main/resources/application.yml`](backend/src/main/resources/application.yml) 中取消 `zhipu-websearch` 配置块的注释。\n3. 在 [`configuration/mcp/mcp_capability_registry.json`](configuration/mcp/mcp_capability_registry.json) 中把需要的条目 `enabled` 改为 `true`。\n4. 通过 `./stop.sh \u0026\u0026 ./start.sh` 完整重启三端使配置生效。\n\n---\n\n## 🏆 SWE-bench Lite 评测\n\nZhikunCode 已完成 SWE-bench Lite（300 实例，pass@1）官方 harness 评测，**Resolve Rate 46.3% (139/300)**。所有评测产物（`all_preds.jsonl`、`results.json`、`metadata.yaml`、轨迹）已开源在 [`docs/swe-bench/20260520/`](docs/swe-bench/20260520/)，可第三方复现。\n\n### 关键指标\n\n| 指标 | 数值 | 出处 |\n|---|---|---|\n| Resolved Instances | **139 / 300 (46.3%)** | `docs/swe-bench/20260520/results/results.json` `resolved=139` |\n| Patch 生成率 | **280 / 300 (93.3%)** | `all_preds.jsonl`（其中 20 条空 patch） |\n| 主干模型 | `qwen-3.6-max-preview` | `docs/swe-bench/20260520/metadata.yaml` |\n| 工具闭集 | Read / Edit / Write / Bash / Grep / Glob | [`swe-bench/swe_bench.py`](swe-bench/swe_bench.py) `ALLOWED_TOOLS` |\n| 单实例预算 | 60 轮 / 900 秒 | [`swe_bench.py`](swe-bench/swe_bench.py) `solve_instance(max_turns=60, timeout=900)` |\n| 并发 worker | 1 | `--workers` 默认值 |\n| 网络 / Sub-agent | 均禁用 | 系统提示显式声明 |\n| 提交命名空间 | `20260520_zhikuncode` | `metadata.yaml` |\n\n### 仓库级表现（`results/resolved_by_repo.json`）\n\n| Repository | Resolved / Total | Resolve Rate |\n|---|---|---|\n| mwaskom/seaborn | 3 / 4 | **75.0%** |\n| django/django | 69 / 114 | **60.5%** |\n| psf/requests | 3 / 6 | 50.0% |\n| sympy/sympy | 38 / 77 | 49.4% |\n| pytest-dev/pytest | 7 / 17 | 41.2% |\n| pydata/xarray | 2 / 5 | 40.0% |\n| astropy/astropy | 2 / 6 | 33.3% |\n| pallets/flask | 1 / 3 | 33.3% |\n| scikit-learn/scikit-learn | 6 / 23 | 26.1% |\n| sphinx-doc/sphinx | 3 / 16 | 18.8% |\n| matplotlib/matplotlib | 4 / 23 | 17.4% |\n| pylint-dev/pylint | 1 / 6 | 16.7% |\n| **Total** | **139 / 300** | **46.3%** |\n\n### 工程亮点（每一项均可在源码定位）\n\n- **Agent-Loop 显式四相位** ANALYZE→LOCATE→FIX→VERIFY，相位边界由系统提示硬约束（[swe_bench.py](swe-bench/swe_bench.py)）\n- **五层上下文压缩级联** Snip / MicroCompact / AutoCompact / CollapseDrain / ReactiveCompact（[ContextCascade.java](backend/src/main/java/com/aicodeassistant/engine/ContextCascade.java)）\n- **413 两阶段恢复** CollapseDrain → ReactiveCompact，保障 60 轮会话收敛于上下文窗口内\n- **自纠错循环** 编译/测试失败结构化再提示，硬上限 3 次（[SelfCorrectionLoop.java](backend/src/main/java/com/aicodeassistant/engine/correction/SelfCorrectionLoop.java) `MAX_ATTEMPTS = 3`）\n\n📄 完整方法学与可复现命令见技术报告：\u003chttps://zhikunqingtao.github.io/zhikuncode/swe-bench-report.html\u003e\n\n---\n\n## 📊 竞品对比\n\n### 功能对比\n\n| 特性 | ZhikunCode | Aider | Cline | Cursor | Claude Code | Copilot |\n|------|:---:|:---:|:---:|:---:|:---:|:---:|\n| 开源免费 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |\n| Web UI | ✅ 全功能 | ⚠️ 实验浏览器 UI | ❌ | ⚠️ Web版 | ✅ | ⚠️ GitHub.com |\n| Docker 一键自托管 | ✅ 完整 Web 服务 | ⚠️ CLI 容器化 | ❌ | ⚠️ 企业付费 | ❌ | ❌ |\n| 国产大模型直连 | ✅ 原生支持 | ⚠️ 需配置兼容 API | ⚠️ 需配置兼容 API | ❌ | ❌ | ❌ |\n| 多 Agent 协作 | ✅ Team/Swarm/Sub | ❌ | ✅ Kanban + CLI 并行 | ✅ Multi-Agents | ✅ Sub-Agents | ✅ /fleet + Agent Mode |\n| 浏览器全流程操控¹ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| 安全沙箱 | ✅ 8层 | ❌ | ❌ | ⚠️ 企业级 | ✅ OS级 | ⚠️ GitHub 权限策略 |\n| MCP 工具扩展 | ✅ | ⚠️ 第三方 | ✅ | ✅ | ✅ | ✅ |\n| CLI 终端工具 | ✅ aica + 35+ 斜杠命令 | ✅ CLI-first | ✅ CLI 2.0 | ✅ Cursor CLI | ✅ CLI-only | ✅ Copilot CLI |\n| 可扩展skill技能系统 | ✅ Markdown 驱动 + 6 级来源 | ❌ | ❌ | ✅ Rules | ✅ Hooks | ❌ |\n| 插件系统 | ✅ Java SPI 插件 + 沙箱隔离 + 热重载 | ❌ | ❌ | ✅ Plugins | ✅ Skills/Hooks | ✅ Plugins |\n| 跨会话记忆 | ✅ 三层记忆 + BM25 搜索 | ❌ | ❌ | ✅ Rules | ✅ Memory | ❌ |\n| 活动追踪与审批 | ✅ L1/L2/L3 三层 | ❌ | ❌ | ❌ | ✅ 权限管理 | ❌ |\n| Activity 持久化 | ✅ SQLite + STOMP | ❌ | ❌ | ❌ | ⚠️ 内存级 | ❌ |\n| 无需安装客户端 | ✅ | ❌ | ❌ | ⚠️ | ✅ | ❌ |\n\n\u003e ¹ **浏览器全流程操控**：部署后任意设备浏览器（包括手机）即可完整操控编码全流程——权限审批、方案协商、任务管控。这与 Cline/Cursor 的\"AI 控制浏览器做自动化测试\"是不同的概念。\n\n### 安全特性对比\n\n| 安全特性 | ZhikunCode | Aider | Cline | Claude Code |\n|---------|:---:|:---:|:---:|:---:|\n| 命令执行沙箱 | 8 层检查 | ❌ 用户审批 | ❌ 用户审批 | ✅ gVisor/Firecracker |\n| 权限管道 | 14 步管线 | ❌ | 简单确认 | 权限管理系统 |\n| 安全测试覆盖 | 308 项 | 未公开 | 未公开 | 未公开 |\n| 敏感路径拦截 | ✅ | ❌ | ❌ | ❌ |\n| 危险命令阻断 | ✅ | ❌ | ❌ | ✅ 部分 |\n| 环境变量白名单 | ✅ | ❌ | ❌ | ❌ |\n\n\u003e **说明：** 以上对比基于各项目公开文档（截至 2026 年 4 月），AI 编程工具迭代迅速，如有不准确之处欢迎提 [Issue](https://github.com/zhikunqingtao/zhikuncode/issues) 指正。Cline CLI 2.0、Cursor 2.0+、Claude Code Desktop、GitHub Copilot /fleet 等均在快速迭代中。\n\u003e\n\u003e **最新动态（2026 年 4 月）：** Claude Code Desktop App 已发布（支持本地+云端混合执行）；Cursor 3.1 新增 Canvas 特性（交互式仪表盘+自定义 UI 组件）；各竞品最新版本号：Aider v0.86+、Cline v1.0.35+、Cursor 3.1+、Claude Code 2.1.119+、GitHub Copilot CLI 1.0.35+。\n\n---\n\n## 🏗️ 架构概览\n\nZhikunCode 采用三端分离架构，Java 后端负责核心编排，React 前端提供交互界面，Python 服务处理代码分析：\n\n```\n┌──────────────────┐      WebSocket / HTTP      ┌──────────────────────┐\n│    Frontend       │ ◄────────────────────────► │      Backend          │\n│  React 18 + TS    │                            │  Java 21 + Spring    │\n│  Vite + Tailwind  │                            │  Boot 3.4            │\n│  :5173 (dev)      │                            │  :8080               │\n└──────────────────┘                            └──────────┬───────────┘\n                                                           │ HTTP\n                                                           ▼\n                                                ┌──────────────────────┐\n                                                │   Python Service      │\n                                                │   FastAPI + Uvicorn   │\n                                                │   :8000               │\n                                                └──────────────────────┘\n```\n\n### 各层职责\n\n| 层 | 技术栈 | 职责 |\n|----|--------|------|\n| **后端** | Java 21, Spring Boot 3.4.x, WebSocket, SQLite | 核心编排引擎、LLM API 路由、Agent 管理、工具执行（48 个内置工具 + MCP 动态扩展）、权限管道、会话持久化 |\n| **前端** | React 18, TypeScript 5.6, Vite 5, TailwindCSS, Monaco Editor, xterm.js, Zustand | 对话式交互 UI、代码编辑器、内置终端、文件浏览器、设置面板、实时流式输出、Agent 协作可视化 |\n| **Python 服务** | FastAPI, Uvicorn, Python 3.11+ | 代码分析、AST 解析、MCP 工具桥接 |\n\n### Docker 部署架构\n\n生产环境通过 Docker 单容器部署，三端服务打包在同一个镜像中：\n\n```\n┌─────────────────────────────────────────────────┐\n│                Docker Container                  │\n│  ┌───────────┐  ┌───────────┐  ┌──────────────┐ │\n│  │  Backend   │  │  Python   │  │   Frontend   │ │\n│  │  :8080     │  │  :8000    │  │  (静态文件)   │ │\n│  └───────────┘  └───────────┘  └──────────────┘ │\n│                                                  │\n│  Volume: zhikun-data (SQLite + 会话数据)          │\n│  Volume: workspace (用户项目代码)                  │\n├──────────────────────────────────────────────────┤\n│  Port: 8080 → 宿主机                              │\n└──────────────────────────────────────────────────┘\n```\n\n### Agent Loop 查询循环\n\nZhikunCode 核心执行引擎 QueryEngine 通过 8 步循环驱动 Agent 决策与工具执行：\n\n```\n压缩级联 → 流式会话创建 → API调用(含API熔断+自适应重试+降级保护) → 响应收集 → 工具结果消费(4层优先级调度) → 6维终止评估 → 工具摘要注入 → 状态更新\n```\n\n**关键子系统：**\n\n| 组件 | 职责 | 配置项 |\n|------|------|--------|\n| IncrementalCollapseManager | 每10轮触发一次增量上下文折叠 | `context.cascade.incremental-collapse.enabled` |\n| ContextCascade | 五层压缩级联（Snip→MicroCompact→AutoCompact→CollapseDrain→ReactiveCompact） | `context.cascade.*` |\n| MicroCompactService | 清除旧工具结果内容，降低上下文体积 | `features.flags.CACHED_MICROCOMPACT` |\n| ModelTierService | 模型降级链管理，30分钟冷却期自动恢复 | `app.model.tier-chain` |\n\n**413 三阶段恢复**：当 API 返回 413 (Payload Too Large) 时，自动执行三阶段恢复：\n1. **Phase 1** — 激进压缩（Context Collapse Drain）\n2. **Phase 2** — 反应式压缩（Reactive Compact）\n3. **Phase 3** — 媒体文件剥离（Media Recovery）\n\n---\n\n## 🔒 安全架构\n\n安全是 ZhikunCode 的核心设计原则。每一条命令执行前，都要经过多层安全检查。\n\n### 8 层 Bash 安全沙箱\n\n所有 Shell 命令执行前，必须通过以下 8 层检查：\n\n| 层级 | 检查内容 | 说明 |\n|------|---------|------|\n| **第 1 层** | 命令解析 | 解析命令结构，识别管道、重定向、子命令 |\n| **第 2 层** | 黑名单过滤 | 三级拦截体系（ABSOLUTE_DENY/HIGH_RISK_ASK/AUDIT_LOG），阻断已知危险命令（`rm -rf /`、`mkfs`、`dd`、`format` 等），含 ReDoS 正则防护 |\n| **第 3 层** | 路径遍历检测 | 防止 `../` 路径穿越攻击，阻断设备路径、UNC 路径 |\n| **第 4 层** | 权限验证 | 14 步权限管道决策，敏感操作需用户审批 |\n| **第 5 层** | 沙箱执行 | 破坏性命令强制在 Docker 沙箱中执行（只读文件系统 + 内存限制 + 网络隔离） |\n| **第 6 层** | 参数净化 | 环境变量白名单、命令注入防护 |\n| **第 7 层** | 输出校验 | 检测异常输出，敏感信息脱敏 |\n| **第 8 层** | 审计日志 | 完整记录每次命令执行，可追溯 |\n\n### 14 步权限管道\n\n权限管道采用**短路返回**设计 —— 命中任何拦截规则立即返回，不继续执行：\n\n```\n请求进入\n  │\n  ├─ 1. Deny 规则检查 ──────────── 命中 → 拒绝\n  ├─ 2. Ask 规则检查 ───────────── 命中 → 询问用户\n  ├─ 3. 工具自身权限检查 ────────── 工具拒绝 → 阻断\n  ├─ 4. 用户交互需求检查 ────────── 需要交互 → 询问\n  ├─ 5. 内容级危险检测 ─────────── rm -rf、chmod 777、eval、sudo 等 → 强制询问\n  ├─ 6. 写路径安全检查 ─────────── 危险目录、符号链接 → 阻断\n  ├─ 7. 危险删除检测 ───────────── rm 危险目标 → 阻断\n  ├─ 8. 环境变量检查 ───────────── 非白名单变量 → 阻断\n  ├─ 9. Hook 注入检查 ──────────── PreToolUse Hook 可阻断\n  ├─ 10. 分类器评估 ────────────── AI 风险评估（AUTO 模式）\n  ├─ 11. 沙箱规则评估 ──────────── 沙箱内操作自动放行\n  ├─ 12. 紧急杀开关 ────────────── 管理员可临时禁用 AUTO\n  ├─ 13. AlwaysAllow 规则 ─────── 匹配白名单 → 放行\n  └─ 14. 模式分支决策 ──────────── DEFAULT/PLAN/AUTO/BYPASS 等模式最终决策\n```\n\n### 受保护路径\n\n以下路径即使在 bypass 模式下也需要用户确认：\n\n- `.git` — Git 仓库数据\n- `.env` — 环境变量和密钥\n- `.ssh` — SSH 密钥\n- `.gnupg` — GPG 密钥\n- `.aws` — AWS 凭证\n\n### 安全测试\n\n- **308 项安全测试**覆盖全部安全路径\n- 包含命令注入、路径穿越、权限绕过等攻击场景\n- **v9.3 深度防御新增**：\n  - **CWE-22 路径穿越**：`CoordinatorService.getScratchpadDir` sessionId 白名单（11 单测）+ `SwarmController.createSwarm` teamName 白名单（8 单测），即使上游 URI 拦截被绕过，白名单仍为最终落盘防线\n  - **跨用户访问隔离（P2-A）**：`BrowserReplayController` 双层闸门 —— sessionId 格式校验返回 400 + principal 归属校验返回 403，MVP 匿名会话兼容\n\n  **v9.3 安全防御汇总：**\n\n  | 防御层级 | 位置 | 防护机制 | 单测数 |\n  |---------|------|---------|-------|\n  | P1-2 | `CoordinatorService.getScratchpadDir` | sessionId 白名单 `^[A-Za-z0-9_-]{1,128}$` | 11 |\n  | E1 | `SwarmController.createSwarm` | teamName 白名单 `^[A-Za-z0-9_-]{1,64}$` | 8 |\n  | P2-A | `BrowserReplayController` | sessionId 格式校验 (400) + principal 归属校验 (403) | — |\n\n- 每次代码变更都会执行完整安全测试套件\n\n### 🧪 质量验证\n\n完整功能测试报告见 [ZhikunCode v9.4 全链路测试报告](docs/test-results/v9.3/ZhikunCode全链路测试报告.md)（2026-05-16）\n\n**持续集成：**\n- **GitHub Actions 自动化流水线**：每次提交自动执行后端编译验证、前端构建、Python 测试及 Docker 镜像构建\n\n**测试覆盖（v9.4）：**\n- **总量**：1948 用例 + 490 性能探针 + 7 安全探针 = **2445**（含 APOS E2E 全功能专项 123 用例：62 Phase 1 + 50 Phase 2 + 11 风险修复）\n- **后端单元/集成测试**：1500 PASS / 0 failure / 0 error / 48 skipped（含 AI Coding 增强 238 单元测试），覆盖率 Inst 42.17% / Branch 30.44%\n- **Python pytest**：47 PASS，覆盖率 25.66%\n- **前端 vitest**：78 PASS / 16 skipped（94 total）\n- **36 模块 REST/WS/LLM/Session 冒烟**：45/45 PASS（42 REST + 1 WS STOMP + 1 LLM 真推理 + 1 Session 持久化）\n- **E2E 差异化链路**：Task 6 多 Agent 协作（CoordinatorEventBus）· Task 7 可视化自动路由（`/visualize` mermaid/json/text）· Task 8 浏览器语义快照 MVP（`/snap`）全链路 PASS\n- **APOS Phase 1 E2E**：62 用例（9 模块，含 28 原始功能 + 34 支撑链路）100% PASS，覆盖 Activity 基础 UI / 数据流转 / 三层展示 / Signal 标记 / Feature Flag / 后端 API / 响应式 / 持久化，含 4 Bug 修复回归\n- **APOS Phase 2 E2E**：5 模块 50 用例（变更影响全景 / Pipeline 视图与 DAG / 异常检测与告警 / 移动端响应式 / Phase 2 集成功能）48 PASS / 2 SKIP，通过率 96%\n- **APOS 风险修复专项**：11 用例 100% PASS（工具调用 / 批量操作 / 并发竞态 / API 降级）\n- **AI Coding 功能增强专项**：6 大模块（SelfCorrectionLoop / 精确Tokenizer / Skill预算安全 / BashTool动态超时 / GitDiffTracker / SearchStrategyRouter）33 用例 + 238 单元测试 + 7 集成测试 + Feature Flag 双向验证，100% PASS\n- **功能完整性验证**：100% 覆盖 v1.0 规划功能\n\n**测试框架详情：**\n\n| 框架 | 层级 | 覆盖范围 | 数量 |\n|------|------|---------|------|\n| JUnit 5 + Mockito | 后端单元/集成测试 | 上下文/权限/技能/插件/LLM/MCP/记忆/并发/SSE/持久化/工具/Coordinator/Swarm/AI Coding 增强 等 | 1500 PASS |\n| Vitest | 前端单元测试 | Store 生命周期/跨 Tab 同步/流式渲染/Immer 不可变性/路由边界 | 78 PASS |\n| Playwright + 节点脚本 | 端到端 E2E | Coordinator WS 订阅 / 可视化 3 种 viewType / 浏览器快照 MVP / APOS Phase 1 全栈 / APOS Phase 2 全栈 | Task 6/7/8/APOS 全绿 |\n| Pytest | Python 服务测试 | Token 估算/文件处理/浏览器自动化/语义快照/代码分析器 | 47 PASS |\n\n**性能基线（v9.3，490 次真实请求采样）：**\n\n| 指标 | p50 | p95 | p99 |\n|-----|-----|-----|-----|\n| REST API（14 端点混合） | 1.5ms | 2.3ms | 4.3ms |\n| WS STOMP 握手 | 2.22ms | 4.58ms | 6.22ms |\n| 浏览器语义快照（热路径） | 9.23ms | 12.20ms | 12.26ms |\n| Swarm 创建 | 2.39ms | 4.90ms | 12.40ms |\n\n**详细测试数据与证据：**\n- v9.3 完整报告：[docs/test-results/v9.3/](docs/test-results/v9.3/)\n- 分模块测试结果：[docs/test-results/](docs/test-results/)\n- 前端 E2E 脚本：[frontend/e2e/](frontend/e2e/)\n- E2E 截图证据：[docs/test-results/screenshots/](docs/test-results/screenshots/)（42 项）\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 36个测试模块详细分类（点击展开）\u003c/summary\u003e\n\n| # | 模块 | 用例数 | 通过率 | 备注 |\n|---|------|--------|--------|------|\n| 1 | 环境准备与三端启动 | 7 | 100% | — |\n| 2 | REST API 基础功能 | 33 | 100% | 逐端点验证 |\n| 3 | WebSocket STOMP 通信 | 8 | 100% | — |\n| 4 | Agent Loop 核心循环 | 9 | 100% | — |\n| 5 | 工具系统与安全 | 10 | 100% | — |\n| 6 | 权限治理与安全 | 6 | 100% | — |\n| 7 | System Prompt 与 LLM | 7 | 100% | — |\n| 8 | 记忆系统 | 7 | 86% | ★ 首次覆盖 |\n| 9 | 技能系统 | 7 | 100% | ★ 首次覆盖 |\n| 10 | 插件系统与 MCP | 11 | 100% | ★ 首次覆盖 |\n| 11 | 多 Agent 协作 | 6 | 100% | — |\n| 12 | Python 服务 | 15 | 100% | 1 BUG 已修复 |\n| 13 | 前端 E2E 与 UI | 7 | 86% | 1 PARTIAL |\n| 14 | 文件历史与补充 API | 11 | 100% | ★ 首次覆盖 |\n| 15 | CLI 命令行工具 aica | 11 | 91% | 2 BUG 已修复 |\n| 16 | 可视化功能 E2E | 19 | 100% | ★ 首次覆盖 |\n| 17 | F3 代码复杂度分析 | 6 | 100% | ★ v1.0 新增 |\n| 18 | F33 变更影响链路分析 | 6 | 100% | ★ v1.0 新增 |\n| 19 | F25 API 契约可视化 | 6 | 100% | ★ v1.0 新增 |\n| 20 | F35 代码→图表自动生成 | 25 | 100% | ★ v1.0 新增 |\n| 21 | F40 代码路径追踪可视化 | 25 | 100% | ★ v1.0 新增 |\n| 22 | 单元测试体系（v9.3 扩展） | 84 | 100% | E2E 模块级测试用例数（后端 JUnit 1500+ 已在别处统计） |\n| 23 | APOS 基础 UI | 4 | 100% | ★ 首次覆盖 |\n| 24 | APOS 数据流转 | 4 | 100% | ★ 首次覆盖 |\n| 25 | APOS 三层展示 | 4 | 100% | ★ 首次覆盖 |\n| 26 | APOS Signal与筛选 | 2 | 100% | ★ 首次覆盖 |\n| 27 | APOS Feature Flag | 2 | 100% | ★ 首次覆盖 |\n| 28 | APOS 后端API验证 | 1 | 100% | ★ 首次覆盖 |\n| 29 | APOS 响应式+健康 | 3 | 100% | ★ 首次覆盖 |\n| 30 | APOS Activity持久化 | 8 | 100% | ★ 首次覆盖 + 4 Bug 修复 |\n| 31 | APOS 变更影响全景 | 6 | 100% | ★ Phase 2 新增 |\n| 32 | APOS Pipeline视图与DAG | 12 | 92% | ★ Phase 2 新增 |\n| 33 | APOS 异常检测与告警 | 10 | 100% | ★ Phase 2 新增，2 SKIP |\n| 34 | APOS 移动端响应式 | 9 | 89% | ★ Phase 2 新增 |\n| 35 | APOS Phase 2集成功能 | 13 | 100% | ★ Phase 2 新增 |\n| 36 | AI Coding 功能增强 | 33 | 100% | ★ v9.4 新增（6子模块 + 238单元 + Feature Flag验证） |\n\n\u003c/details\u003e\n\n---\n\n## 🎯 skill技能系统\n\nZhikunCode 的skill技能系统（Skill System）是一个 **Markdown 驱动的可扩展工作流引擎**。每个技能就是一个 `.md` 文件，用 YAML frontmatter 定义元数据，用 Markdown 正文定义执行指令。\n\n### 6 个内置技能\n\n开箱即用，输入 `/技能名` 即可调用：\n\n| 技能 | 命令 | 功能 |\n|------|------|------|\n| **智能提交** | `/commit` | 分析暂存区变更，按 Conventional Commits 格式生成 commit message |\n| **代码审查** | `/review` | 审查未提交变更，按 P0/P1/P2 严重程度分类问题 |\n| **智能修复** | `/fix` | 根据错误信息诊断根因，应用最小化修复并验证 |\n| **智能测试** | `/test` | 为指定代码或近期变更生成/运行测试，覆盖边界情况 |\n| **PR 助手** | `/pr` | 分析分支差异，生成结构化 PR 描述和审查说明 |\n\n### 6 级加载源优先级\n\n同名技能按优先级链覆盖，高优先级自动屏蔽低优先级：\n\n```\nmanaged \u003e user \u003e project \u003e plugin \u003e bundled \u003e mcp\n```\n\n| 来源 | 目录 | 说明 |\n|------|------|------|\n| **managed** | 策略管理目录 | 企业统一下发的技能 |\n| **user** | `~/.zhikun/skills/` | 用户全局自定义技能 |\n| **project** | `.zhikun/skills/` | 项目级技能，随代码库分发 |\n| **plugin** | 插件提供 | JAR 插件内嵌的技能 |\n| **bundled** | 内置 | 6 个开箱即用技能 |\n| **mcp** | MCP 构建 | 通过 MCP 协议注册的技能 |\n\n### 自定义技能\n\n在 `~/.zhikun/skills/` 或项目根目录 `.zhikun/skills/` 下创建 `.md` 文件：\n\n```markdown\n---\ndescription: \"将代码翻译为指定语言\"\narguments:\n  - language\n---\n\n# 翻译任务\n\n将用户选中的代码翻译为 {{language}}，保持原有逻辑和注释风格。\n```\n\n调用方式：`/translate language=python` 或 `/translate python`\n\n**支持的 frontmatter 字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `description` | string | 技能描述 |\n| `name` | string | 显示名称（覆盖文件名） |\n| `arguments` | list | 参数定义列表 |\n| `argument_hint` | string | 参数提示文本 |\n| `when_to_use` | string | 模型自动调用的条件 |\n| `allowed_tools` | list | 允许使用的工具白名单 |\n| `context` | string | `inline`（默认，注入当前对话）或 `fork`（创建独立子代理） |\n| `model` | string | 指定模型（`inherit` 使用父模型） |\n\n\u003e 技能文件支持热重载 — 保存后自动生效，无需重启服务。底层使用 Java NIO WatchService + 500ms 防抖机制监听文件变更。\n\n**安全与预算控制：**\n- **Token 预算限制**：单 Skill ≤5000 tokens / 会话总计 ≤25000 tokens，防止资源滥用\n- **工具白名单**：Skill 只能调用 frontmatter 中 `allowed_tools` 声明的工具\n- **注入防护**：Shell 注入三向量拦截（`$()` / 反引号 / 管道），参数长度限制 2000 字符\n- **Fork 深度控制**：fork 模式 Skill 嵌套深度 ≤3 层，防止无限递归\n\n---\n\n## 🧩 插件系统\n\nZhikunCode 的插件系统通过标准 **Java SPI（ServiceLoader）** 机制发现和加载第三方 JAR 插件，提供四大桥接能力：命令注册、工具注册、钩子拦截、MCP 服务器集成。通过 `plugin.enabled` Feature Flag 控制启停。\n\n### 四大桥接能力\n\n| 桥接类型 | 说明 | 示例 |\n|---------|------|------|\n| **命令注册** | 插件可注册自定义斜杠命令，自动添加插件前缀 | `/myplugin:hello` |\n| **工具注册** | 插件可提供自定义工具供 AI Agent 调用 | 自定义代码分析工具 |\n| **钩子拦截** | 插件可在关键事件前后执行自定义逻辑 | 工具执行前安全审计 |\n| **MCP 服务器** | 插件可注册 MCP 服务器扩展 AI 能力 | 连接外部数据源 |\n\n### 安全特性\n\n- **PluginClassLoader 沙箱隔离** — 插件通过包白名单访问宿主 API：核心 API 包（`com.aicodeassistant.plugin.*`、`tool.*`、`command.*`、`mcp.*`）、标准库（`java.*`、`javax.*`、`jdk.*`、`sun.*`、`org.slf4j.*`）、基础框架（`org.springframework.*`、`com.fasterxml.jackson.*`、`jakarta.*`）。未在白名单中的宿主类访问会抛出 `ClassNotFoundException`\n- **钩子执行超时保护** — Virtual Thread + `CompletableFuture.orTimeout(5s)`，超时自动放行，防止插件阻塞主流程\n- **JAR 文件验证** — 加载前校验文件存在性、JAR 格式合法性、大小限制（默认 50MB）、SPI 配置文件（`META-INF/services/`）完整性\n- **API 版本兼容检查** — 插件声明 `minApiVersion` / `maxApiVersion`，宿主自动校验兼容性\n\n### 热重载机制\n\n支持运行时重新加载所有插件，无需重启服务：\n\n- 使用 `ReentrantReadWriteLock` 保证热重载期间的并发安全\n- 重载流程：卸载所有插件（注销命令/工具/钩子/MCP + 关闭 ClassLoader）→ 重新扫描加载\n- 触发方式：`/reload-plugins` 斜杠命令 或 REST API\n\n### 8 种钩子事件类型\n\n插件可注册以下事件钩子，在关键节点执行自定义逻辑：\n\n| 事件类型 | 触发时机 |\n|---------|----------|\n| `PreToolExecution` | 工具执行前 |\n| `PostToolExecution` | 工具执行后 |\n| `UserPromptSubmit` | 提示词提交时 |\n| `SessionStart` | 会话开始 |\n| `SessionEnd` | 会话结束 |\n| `TaskCompleted` | 任务完成 |\n| `Notification` | 通知事件 |\n| `Stop` | 停止事件 |\n\n### 插件开发指南\n\n开发一个 ZhikunCode 插件只需四步：\n\n**1. 实现 `PluginExtension` SPI 接口**\n\n```java\npublic class MyPlugin implements PluginExtension {\n    @Override public String name() { return \"my-plugin\"; }\n    @Override public String version() { return \"1.0.0\"; }\n\n    @Override\n    public List\u003cCommand\u003e getCommands() {\n        return List.of(/* 自定义命令 */);\n    }\n\n    @Override\n    public void onLoad(PluginContext ctx) {\n        ctx.getLogger().info(\"Plugin loaded!\");\n    }\n}\n```\n\n**2. 在 `META-INF/services/` 中注册 SPI**\n\n```\n# META-INF/services/com.aicodeassistant.plugin.PluginExtension\ncom.example.MyPlugin\n```\n\n**3. 将 JAR 放入 `~/.zhikun/plugins/` 目录**\n\n**4. 重启服务或执行 `/reload-plugins` 热重载**\n\n\u003e `PluginExtension` 接口采用默认方法设计 — 最小实现仅需 `name()` 和 `version()`，其余能力（命令/工具/钩子/MCP）按需覆写。\n\n---\n\n## 🧠 记忆系统\n\nZhikunCode 内置三层记忆架构，让 AI 助手能够 **跨会话记住你的偏好、项目约定和工作流程**。\n\n### 三层记忆架构\n\n| 层级 | 文件 | 作用域 | 说明 |\n|------|------|--------|------|\n| **个人记忆** | `~/.ai-code-assistant/MEMORY.md` | 全局跨项目 | AI 自动记录用户偏好、常用模式、错误解决方案 |\n| **项目记忆** | `zhikun.md` / `zhikun.local.md` | 当前项目 | 项目级编码约定、架构决策、构建流程 |\n| **团队记忆** | `.zhikun/team-memories/*.md` | 团队共享 | 随代码库分发的团队规范和共享知识 |\n\n### 记忆分类\n\n基于认知心理学模型的设计分类（实现层面通过文件路径和元数据标签区分），记忆自动归类为四种类型：\n\n| 分类 | 说明 | 示例 |\n|------|------|------|\n| **语义记忆**（semantic） | 项目知识、用户偏好、技术约定 | 「这个项目使用 JUnit 5 + AssertJ」 |\n| **事件记忆**（episodic） | 具体操作历史、调试经过 | 「上次部署时端口冲突的解决方法」 |\n| **程序记忆**（procedural） | 常用工作流、部署流程 | 「每次提交前先跑 `mvn test`」 |\n| **团队记忆**（team） | 团队级共享知识和规范 | 「API 返回统一使用 Result 包装」 |\n\n### 自动记忆与搜索\n\nAI 在交互过程中通过内置的 MemoryTool 自动记录和检索记忆：\n\n- **自动写入** — AI 发现重要信息时主动记录（用户偏好、项目规范等）\n- **自动加载** — 每次会话启动时自动注入系统提示，无需手动操作\n- **BM25 搜索** — 纯 Java 实现的 BM25 搜索引擎，支持中英文混合检索（Unigram + Bigram 中文分词）\n- **来源追踪** — 支持记忆来源追踪（source 字段），区分 REST API 创建与 LLM 工具创建的记忆\n- **LLM 重排** — 可选的 LLM 精排服务，BM25 粗筛后由大模型进行相关性精排\n\n### 项目记忆文件\n\n在项目根目录创建记忆文件，AI 会自动读取并遵循：\n\n```markdown\n# zhikun.md — 项目约定（随代码库提交）\n\n## 编码规范\n- Java 方法命名使用 camelCase\n- 测试类以 Test 结尾\n\n## 构建流程\n- 提交前必须跑 `./mvnw test`\n- Commit 采用 Conventional Commits 格式\n```\n\n```markdown\n# zhikun.local.md — 本地配置（不提交，加入 .gitignore）\n\n## 本地环境\n- 我的 API Key 在 .env 文件中\n- 本地数据库端口: 5432\n```\n\n\u003e 项目记忆文件向上遍历 5 层目录加载，单文件上限 100KB。`zhikun.md` 随代码库提交用于团队共享，`zhikun.local.md` 用于个人本地配置。\n\n### 安全保护\n\n- 截断保护：个人记忆最多 200 行 / 25KB，防止系统提示 Token 爆炸\n- 自动压缩：超出 50,000 字符时自动压缩，保留最新 70%\n- 自动过期：90 天未访问的记忆自动清理\n- 路径穿越防护：项目记忆写入时校验绝对路径和符号链接\n\n---\n\n## 💻 CLI 工具\n\n除了 Web UI，ZhikunCode 还提供完整的命令行能力，覆盖三种场景：\n\n### Python CLI（aica）— 终端 AI 编程\n\n`aica` 是 ZhikunCode 的命令行客户端，设计为 UNIX 管道一等公民：\n\n```bash\n# 安装\ncd python-service\npip install -e \".[cli]\"\n\n# 基础使用\naica \"帮我重构这个函数\"\n\n# 管道输入 — 像 grep/sed 一样组合\ncat src/main.py | aica \"review this code\"\n\n# 结构化输出 + jq 处理\naica -f json \"list all API endpoints\" | jq '.result'\n\n# 流式输出\naica -f stream-json \"refactor this module\"\n\n# 继续上次对话\naica --continue \"fix the bug we just discussed\"\n```\n\n**核心特性：**\n\n| 特性 | 说明 |\n|------|------|\n| 三种输出格式 | `text`（终端 Markdown 渲染）/ `json`（结构化）/ `stream-json`（SSE 流式） |\n| 管道支持 | 自动读取 stdin，与 shell 管道无缝组合 |\n| 权限模式 | `--permission-mode dont_ask/bypass/default` 控制安全策略（CLI 默认 `dont_ask`） |\n| 会话管理 | `--continue` 继续上次会话，`--resume \u003cid\u003e` 恢复指定会话 |\n| 模型选择 | `--model` 指定模型，`--effort` 控制推理深度 |\n| 工具控制 | `--allowed-tools` / `--disallowed-tools` 白名单/黑名单 |\n| 退出码 | 0=成功，1=通用错误，2=参数错误，3=连接错误，4=认证错误，130=Ctrl+C 中断 |\n\n\u003e `aica` 通过 HTTP/SSE 连接 ZhikunCode 后端，共享同一套 Agent 引擎、工具集和安全架构。适合 CI/CD 集成和脚本自动化场景。\n\n### 35+ 斜杠命令 — Web UI 快捷操作\n\n\u003e 以下斜杠命令在 Web UI 中使用，`aica` CLI 通过自然语言 prompt 访问后端 Agent 引擎实现相同能力。\n\n在 Web UI 中输入 `/` 或按 `Ctrl+K` 打开命令面板，支持模糊搜索和键盘导航：\n\n| 类别 | 命令 | 说明 |\n|------|------|------|\n| **核心** | `/help` `/clear` `/exit` | 帮助、清除对话、退出 |\n| **模型** | `/model` | 查看/切换 LLM 模型 |\n| **诊断** | `/doctor` | 9 项系统诊断（Java/LLM/Git/JVM/Python/磁盘） |\n| **压缩** | `/compact` | 手动触发上下文压缩，可附带指令（如 `/compact focus on API`） |\n| **Git** | `/diff` `/commit` `/review` | 代码差异、生成 commit message、代码审查 |\n| **配置** | `/config` `/permissions` | 查看配置、权限模式管理 |\n| **会话** | `/session` `/resume` | 会话信息、恢复历史会话 |\n| **成本** | `/cost` `/usage` | Token 用量、费用统计 |\n| **MCP** | `/mcp-servers` `/mcp-tools` | MCP 服务管理 |\n| **深度分析** | `/ultrareview` | AI 深度审查（架构+安全+性能+并发） |\n| **浏览器** | `/snap` | 语义快照 —— 捕获当前页面 DOM 结构与交互元素，生成 JSON 格式快照 |\n| **可视化** | `/visualize mermaid\\|json\\|text` | 自动路由推送 —— 流式渲染 Mermaid 图表、JSON 数据或纯文本可视化结果 |\n\n\u003e 命令输入错误时，系统会基于 Levenshtein 距离自动建议相似命令。\n\n---\n\n## 📱 浏览器全流程操控\n\n这是 ZhikunCode 的核心差异化特性。与 Cursor、Cline 等需要安装桌面客户端或 IDE 插件的工具不同，ZhikunCode 是一个独立的 Web 应用 —— 部署一次，任何设备的浏览器都能用。\n\n### 为什么这很重要？\n\n| 场景 | 传统 AI 编程工具 | ZhikunCode |\n|------|-----------------|------------|\n| 通勤路上想审批一个权限请求 | ❌ 必须打开电脑 | ✅ 手机浏览器直接操作 |\n| 同事想试用你的 AI 编程助手 | ❌ 需要安装 VS Code + 插件 | ✅ 发一个链接就行 |\n| 部署到团队服务器多人共用 | ❌ 每人都要装客户端 | ✅ 浏览器打开就用 |\n| iPad 上改代码 | ❌ 没有原生客户端 | ✅ Safari/Chrome 直接用 |\n\n### 完整的浏览器操控能力\n\n通过浏览器，你可以完成 AI 编程的全部流程：\n\n- **对话式编程** — 输入自然语言需求，Agent 自动生成代码，实时流式输出\n- **权限审批** — 每个敏感操作都会弹出审批请求，你可以 允许/拒绝/修改\n- **方案协商** — Agent 提出方案后可以在浏览器中讨论、修改、确认\n- **任务管控** — 查看任务进度、中断执行、重新分配\n- **文件浏览** — 在浏览器中直接查看和导航项目文件树\n- **Agent 协作可视化** — 多 Agent 模式下实时查看各 Agent 工作状态\n\n### 实时通信\n\n前后端通过 **STOMP over SockJS** 保持实时连接（自动协商 WebSocket → xhr-streaming → xhr-polling 降级）：\n\n- **流式输出** — LLM 响应逐字输出，无需等待完成\n- **权限冒泡** — 子 Agent 的权限请求实时推送到浏览器\n- **状态同步** — Agent 工作状态变化即时反映在 UI 上\n- **心跳保活** — 双向 10s 心跳检测，断线自动重连（指数退避 1s→10s）\n- **消息保障** — 128KB 消息大小限制，1MB 发送缓冲，30s 发送超时\n\n---\n\n## 🤖 多 Agent 协作\n\nZhikunCode 提供三种 Agent 协作模式和五种类型化 Agent，适用于不同复杂度的任务。\n\n### 五种内置 Agent 类型\n\n基于 Java 21 sealed interface 实现编译期穷尽性检查，每种 Agent 有独立的工具集、模型偏好和系统提示：\n\n| Agent 类型 | 用途 | 工具集 | 模型偏好 |\n|-----------|------|--------|----------|\n| **通用 (general-purpose)** | 完整实现能力 | 全部工具，无限制 | 继承父级 |\n| **探索 (explore)** | 只读代码搜索 | 禁止 FileEdit/FileWrite | 轻量模型 (light) |\n| **验证 (verification)** | 对抗性测试验证 | 禁止 FileEdit/FileWrite | 继承父级 |\n| **规划 (plan)** | 分析与方案设计 | 禁止 FileEdit/FileWrite | 继承父级 |\n| **引导 (guide)** | 文档与使用指南 | 仅 Glob/Grep/FileRead/WebFetch/WebSearch | 轻量模型 (light) |\n\n\u003e 所有子 Agent 均禁止调用 Agent/TeamCreate/TeamDelete 工具，从架构层面防止无限递归。\n\n### Team 模式 — 固定分工\n\n预定义角色的团队协作。每个 Agent 有明确的职责和工具集。\n\n```\n┌─────────────┐\n│   Leader     │  任务分配与结果聚合\n└──────┬──────┘\n       │\n  ┌────┴────┐\n  ▼         ▼\n┌──────┐ ┌──────┐\n│Agent A│ │Agent B│  并行执行，独立工具集\n│后端开发│ │前端开发│\n└──────┘ └──────┘\n```\n\n- 适用场景：前后端分离开发、测试+开发协作\n- 通过 `TeamMailbox` 进行 Agent 间异步消息传递（ConcurrentLinkedQueue）\n- 通过 `SharedTaskList` 共享 FIFO 任务队列，支持任务认领与状态追踪\n- `InProcessBackend` 使用 Virtual Thread 并发执行多个 Worker\n\n### Swarm 模式 — 动态协商\n\n基于 Java 21 虚拟线程的动态多 Worker 协作，由 Coordinator 编排四阶段工作流：\n\n```\nResearch → Synthesis → Implementation → Verification\n```\n\n四阶段严格顺序不可跳过，每个阶段记录时间戳和结果摘要。`CoordinatorWorkflow` 管理完整的阶段生命周期。\n\n- 适用场景：复杂重构、大规模代码迁移\n- Worker 数量动态调整，无需预声明\n- 每个 Worker 一个 Virtual Thread，30 分钟超时保护\n- Worker 工具集通过 allowList/denyList 精确控制\n- 权限冒泡到 UI（`LeaderPermissionBridge`），支持并发堆叠展示多个权限请求，每个请求独立 60 秒倒计时，支持单个或批量批准/拒绝操作，超时自动拒绝防止死锁\n- 实时状态通过 STOMP WebSocket 推送到前端\n- 活跃 Swarm 使用 Caffeine 缓存管理，4 小时 TTL 自动清理异常实例\n\n### SubAgent 模式 — 主从委派\n\n主 Agent 将子任务委派给独立的子 Agent 执行，支持三种隔离级别：\n\n| 隔离模式 | 行为 | 适用场景 |\n|---------|------|----------|\n| **NONE** | 共享父 Agent 工作目录 | 轻量级子任务 |\n| **WORKTREE** | 创建独立 Git Worktree，完成后自动合并或丢弃 | 需要隔离的实验性变更 |\n| **Fork** | 继承父会话完整消息历史，复用 LLM KV cache | 需要完整上下文的延续任务 |\n\n- 支持后台异步执行（`BackgroundAgentTracker`），通过 WebSocket 实时推送启动/完成/失败事件，用户可实时监控代理执行进度\n- 单个 Agent 5 分钟超时，结果最大 100,000 字符截断保护\n\n### 三层并发安全\n\n`AgentConcurrencyController` 通过 Semaphore + 会话级计数器强制执行三层限制：\n\n| 维度 | 限制 | 保护目标 |\n|------|------|----------|\n| 全局并发 | ≤ 30 个 Agent | 内存与 API 并发压力 |\n| 会话并发 | ≤ 10 个 Agent/会话 | 交互式场景资源隔离 |\n| 嵌套深度 | ≤ 3 层 | 防止无限递归 |\n\n槽位通过 RAII 模式（`try-with-resources`）自动释放，确保异常路径不会泄漏资源。\n\n### 模型别名路由\n\nAgent 使用三级回退策略解析模型：用户参数 → Agent 类型默认 → 全局默认。通过 `application.yml` 中的 `agent.model-aliases` 配置别名映射（如 `light → qwen-plus`），避免硬编码模型名称，一处配置全局生效。\n\n---\n\n## 🧩 MCP 工具扩展\n\nZhikunCode 实现了标准的 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 协议，支持通过 SSE 传输层连接外部 MCP 服务：\n\n### 内置 MCP 工具\n\n| 工具 | 说明 | 来源 |\n|------|------|------|\n| **万相 2.5 图像生成** | AI 绘画，输入文本生成图片 | DashScope MCP |\n| **万相 2.5 图像编辑** | AI 图像编辑（图生图） | DashScope MCP |\n| **网络搜索 Pro** | 联网搜索，返回网页摘要 | DashScope MCP |\n\n### 自定义 MCP 工具\n\n在 `configuration/mcp/mcp_capability_registry.json` 中注册新的 MCP 工具：\n\n```json\n{\n  \"id\": \"mcp_your_tool\",\n  \"name\": \"你的工具名称\",\n  \"toolName\": \"mcp_server_tool_name\",\n  \"sseUrl\": \"https://your-mcp-server/sse\",\n  \"domain\": \"your_domain\",\n  \"category\": \"MCP_TOOL\",\n  \"enabled\": true\n}\n```\n\n---\n\n## 🛠️ 内置工具集\n\nZhikunCode 内置 48 个工具 + MCP 动态扩展，覆盖开发全流程：\n\n| 分类 | 工具 | 说明 |\n|------|------|------|\n| **文件操作** | FileRead、FileWrite、FileEdit、NotebookEdit | 读取、写入、编辑文件（原子写入+SHA-256冲突检测），支持 Jupyter Notebook |\n| **代码搜索** | GrepTool、GlobTool、ToolSearch、LspTool、SnipTool | 正则搜索、文件匹配、工具搜索、LSP 语言服务（含调用层级分析）、代码片段、智能分层搜索（作用域感知 4 层优先级路由） |\n| **命令执行** | BashTool、PowerShellTool、REPLTool | Shell 沙箱执行（动态超时分类 + 指数退避恢复）、Windows PowerShell、交互式 REPL 会话 |\n| **Git 操作** | GitTool、Worktree | Git 命令执行、Worktree 管理 |\n| **Web 工具** | WebSearch、WebFetch、WebBrowser | 网络搜索、网页抓取、浏览器自动化 |\n| **Agent 协作** | AgentTool | 创建和管理子 Agent |\n| **任务管理** | 任务创建/获取/列表/更新/停止/输出 | SharedTaskList 任务协作（6 个工具） |\n| **交互** | AskUserQuestion、Brief、Sleep、TodoWrite | 用户提问、简报、等待、任务清单 |\n| **定时任务** | CronCreate、CronList、CronDelete | 定时任务管理 |\n| **计划模式** | EnterPlanMode、ExitPlanMode、VerifyPlan | 先规划后执行的工作流 |\n| **配置** | ConfigTool、SendMessage、SyntheticOutput | 配置管理、消息发送、合成输出 |\n| **监控** | MonitorTool、CtxInspect、TerminalCapture | 系统监控、上下文检查、终端输出捕获 |\n| **MCP 扩展** | MCP 工具适配器 | 连接外部 MCP 服务（动态注册） |\n\n---\n\n## 📈 可视化\n\nZhikunCode 内置 11 项可视化能力，让 AI 编程过程中的数据和状态一目了然：\n\n| 功能 | 说明 |\n|------|------|\n| **Mermaid 图表渲染** | AI 回复中的 mermaid 代码块自动渲染为交互式矢量图，支持复制 SVG / 下载 PNG |\n| **API 序列图** | 自动从会话中提取工具调用记录，生成 Mermaid 序列图，支持过滤和详情查看 |\n| **Agent DAG** | 实时展示多 Agent 协作的任务依赖图，基于 React Flow，支持 TB/LR 布局切换 |\n| **Git 时间线** | 可视化 Git 提交历史，支持 Diff 查看和 Blame 视图，commit 类型自动着色 |\n| **工具进度可视化** | 工具执行过程显示进度条、ETA 预估和迷你日志查看器 |\n| **文件树导航** | 侧边栏项目文件树，支持搜索过滤、虚拟滚动、文件类型图标 |\n| **代码复杂度 Treemap** | 基于 recharts 的交互式矩形面积图，面积映射代码行数(LOC)，颜色映射风险等级(A-E)，支持钻取导航、语言/风险过滤、统计卡片，Python radon + tree-sitter 多语言分析 |\n| **变更影响链路** | 基于 @xyflow/react 的 DAG 可视化，展示代码变更的影响传播路径，LibCST 精准解析 Python 调用图，BFS 逐层传播分析，节点类型/置信度/影响层级一目了然 |\n| **API 契约可视化** | 自动合并 Java + Python 双端 OpenAPI 规范，端点列表按 Tag 分组、HTTP 方法颜色编码、Schema 递归展示，支持 All/Java/Python 数据源切换 |\n| **代码→图表自动生成** | 输入代码文件路径自动生成 Mermaid 时序图/流程图，Python LibCST + tree-sitter 多语言解析，调用链 BFS 遍历自动识别 Controller/Service/Repository 参与者，五维置信度评分(0-1)，Monaco Editor 实时编辑源码，SVG 复制 / PNG 下载导出，支持 1-5 级遍历深度控制 |\n| **代码路径追踪可视化** | 基于 @xyflow/react 的代码调用路径追踪可视化，Python CodePathTracer 正向 BFS 追踪 + 六层分层标注（Controller/Service/Repository/Database/External/Utility），dagre TB 布局算法自动排列节点，自定义 LayerNode 按层级着色，MiniMap 全局导览 + LayerStatsBar 层级统计，支持 API 端点扫描、参数追踪、节点点击详情、maxDepth 深度控制，通过侧边栏\"代码路径\" Tab 进入 |\n| **Activity Panel 活动面板** | 三层卡片展示（L1 紧凑 → L2 展开 → L3 Portal），实时显示工具执行状态、Signal 风险标记、审批决策状态 |\n\n\u003e **v9.3 新增**：`/visualize` 命令通过 VisualizationAutoRouter 自动推送三种格式（mermaid / json / text），WS STOMP `/app/command` 端到端延迟 p50 \u003c 3ms。\n\n---\n\n## ⚙️ 配置说明\n\n### 环境变量\n\n环境变量通过 `.env` 文件管理。复制 `.env.example` 后按需修改：\n\n**多 Provider 配置（推荐）：**\n\n| 变量 | 必填 | 默认值 | 说明 |\n|------|:---:|--------|------|\n| `LLM_PROVIDER_DASHSCOPE_API_KEY` | — | — | 千问/DashScope API Key |\n| `LLM_PROVIDER_DEEPSEEK_API_KEY` | — | — | DeepSeek API Key |\n| `LLM_PROVIDER_MOONSHOT_API_KEY` | — | — | Moonshot/Kimi API Key |\n| `LLM_DEFAULT_MODEL` | — | qwen3.7-max | 默认模型（未显式选择时使用） |\n\n\u003e 多 Provider 模式下至少配置一个 Provider 的 API Key 即可。前端支持自由切换已配置的 Provider。\n\n**单 Provider 配置（向后兼容）：**\n\n| 变量 | 必填 | 默认值 | 说明 |\n|------|:---:|--------|------|\n| `LLM_API_KEY` | ✅ | — | LLM 服务商的 API Key |\n| `LLM_BASE_URL` | — | DashScope | LLM API 地址 |\n| `LLM_DEFAULT_MODEL` | — | qwen3.7-max | 默认模型 |\n| `LLM_MODELS` | — | 千问系列 | 可用模型列表（逗号分隔） |\n\n\u003e 如 `LLM_PROVIDER_*` 均为空，系统自动回退到单 Provider 模式。\n\n**通用配置：**\n\n| 变量 | 必填 | 默认值 | 说明 |\n|------|:---:|--------|------|\n| `ZHIKUN_PORT` | — | 8080 | Docker 映射的宿主机端口 |\n| `SPRING_PROFILES_ACTIVE` | — | production | Spring 配置文件 |\n| `JAVA_OPTS` | — | -Xms256m -Xmx1024m | JVM 参数 |\n| `WORKSPACE_PATH` | — | ./workspace | 挂载到容器的工作目录 |\n| `ALLOW_PRIVATE_NETWORK` | — | true（Docker） | Docker 环境下允许私有网段免认证访问 |\n| `LOG_DIR` | — | /app/log | 容器内日志目录 |\n| `MCP_REGISTRY_PATH` | — | 自动配置 | MCP 能力注册表文件路径 |\n\n**高级配置：**\n\n| 变量 | 必填 | 默认值 | 说明 |\n|------|:---:|--------|------|\n| `ZHIKUN_COORDINATOR_MODE` | — | 0 | Feature flag，启用协调器模式（0=关闭，1=开启） |\n| `LLM_PROVIDER_DASHSCOPE_MODELS` | — | qwen3.7-max,qwen3.6-plus | DashScope 可用模型列表（逗号分隔） |\n| `LLM_PROVIDER_DEEPSEEK_MODELS` | — | deepseek-v4-pro,deepseek-v4-flash | DeepSeek 可用模型列表（逗号分隔） |\n| `LLM_PROVIDER_MOONSHOT_MODELS` | — | kimi-k2.6,moonshot-v1-auto | Moonshot 可用模型列表（逗号分隔） |\n\n**上下文管理配置（application.yml）：**\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `context.cascade.incremental-collapse.enabled` | true | 启用增量折叠 |\n| `context.cascade.incremental-collapse.segment-turns` | 10 | 折叠触发间隔（轮数） |\n| `context.cascade.incremental-collapse.session-timeout-minutes` | 30 | 会话超时时间 |\n| `features.flags.CACHED_MICROCOMPACT` | true | 启用微压缩服务 |\n| `features.flags.TOKEN_BUDGET` | false | Token 预算控制（默认关闭，需要时手动开启） |\n| `features.flags.SELF_CORRECTION_LOOP` | false | 执行失败自动诊断修复循环（编译错误/测试失败，最多重试3次） |\n| `features.flags.PRECISE_TOKENIZER` | false | 精确 Token 计数（调用 Python tiktoken，替代字符估算） |\n| `features.flags.GIT_DIFF_TRACKER` | false | Git 变更追踪与编辑历史聚合 |\n| `features.flags.SEARCH_STRATEGY_ROUTER` | false | 作用域感知分层搜索策略路由 |\n\n### Docker 资源限制\n\n默认资源配置（可在 `docker-compose.yml` 中调整）：\n\n| 配置项 | 默认值 |\n|--------|--------|\n| 内存上限 | 4GB |\n| 内存预留 | 1GB |\n| 健康检查间隔 | 30s |\n| 启动等待时间 | 60s |\n\n\u003e **注意：** 首次构建镜像期间需要更多内存（Maven 编译 + npm build）。如果构建失败，请在 Docker Desktop 设置中增加内存分配至 6GB 以上。运行时容器内存上限为 4GB（可在 docker-compose.yml 中调整）。\n\n---\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ1：支持哪些大模型？\u003c/b\u003e\u003c/summary\u003e\n\n支持所有兼容 OpenAI API 格式的模型，包括：\n\n- **千问 / DashScope**（国内直连，默认推荐）\n- **DeepSeek**（国内直连）\n- **Moonshot / Kimi**（国内直连）\n- **OpenAI GPT-4o / GPT-4**（需外网访问）\n- **Anthropic Claude**（通过 OpenAI 兼容 API）\n- **本地模型**（通过 Ollama、vLLM 等）\n\n只要是兼容 OpenAI API 格式的服务商，配置好 `LLM_BASE_URL` 和 `LLM_API_KEY` 就能用。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ2：Docker 部署需要什么配置？\u003c/b\u003e\u003c/summary\u003e\n\n**最低要求：**\n- Docker 20.10+\n- Docker Compose V2\n- 4GB+ 可用内存\n- 网络能访问 LLM API 端点（用千问的话国内网络就行）\n\n**部署只需 3 步：**\n```bash\ngit clone https://github.com/zhikunqingtao/zhikuncode.git \u0026\u0026 cd zhikuncode\ncp .env.example .env  # 编辑填入 API Key\ndocker compose up -d  # 启动\n```\n\n打开 `http://localhost:8080` 即可使用。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ3：数据存在哪里？安全吗？\u003c/b\u003e\u003c/summary\u003e\n\n**所有数据存在本地**，不会发送到任何第三方服务器：\n\n- **会话数据** — SQLite 数据库，存储在 Docker Volume `zhikun-data` 中\n- **项目代码** — 通过 Volume 挂载你本地的项目目录\n- **API Key** — 只存在你的 `.env` 文件和运行中的容器环境变量中\n\nZhikunCode 不运行任何遥测服务。API Key 直连你配置的 LLM 服务商，中间不经过任何代理或中转服务器。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ4：支持内网 / 离线部署吗？\u003c/b\u003e\u003c/summary\u003e\n\n**支持。** Docker 部署后完全在内网运行。\n\n- **使用国产模型（千问/DeepSeek）：** 国内网络直连，无需科学上网\n- **完全离线：** 搭配 Ollama 运行本地模型，`LLM_BASE_URL=http://host.docker.internal:11434/v1`\n- **企业内网：** 只需确保服务器能访问 LLM API 端点即可\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ5：多 Agent 协作怎么用？\u003c/b\u003e\u003c/summary\u003e\n\nZhikunCode 提供三种协作模式：\n\n- **Team** — 固定分工：创建团队后，每个 Agent 按角色分工并行执行\n- **Swarm** — 动态协商：自动拆解任务，Worker 动态分配，四阶段工作流\n- **SubAgent** — 主从委派：主 Agent 将子任务委派给子 Agent，支持隔离执行\n\n在对话中直接描述需求即可触发，例如：\n\u003e \"重构这个项目的用户认证模块，一个 Agent 负责后端 API，一个负责前端页面\"\n\nAgent 会自动选择合适的协作模式。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ6：和 VS Code 插件（Copilot/Cline）冲突吗？\u003c/b\u003e\u003c/summary\u003e\n\n**不冲突。** ZhikunCode 是独立的 Web 应用，不依赖任何 IDE，不需要安装插件。\n\n你可以同时使用：\n- **VS Code + Copilot** —— 做行级代码补全\n- **ZhikunCode** —— 做对话式 Agent 编程、复杂任务编排\n\n两者互补，不冲突。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ7：怎么贡献代码？\u003c/b\u003e\u003c/summary\u003e\n\n欢迎贡献！详细流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n简单步骤：\n1. Fork 仓库\n2. 创建功能分支 (`git checkout -b feature/your-feature`)\n3. 提交代码\n4. 创建 Pull Request\n\n推荐从标记为 `good first issue` 的 Issue 开始。\n\n**开发环境需要：** JDK 21、Node.js 22+、Python 3.11~3.12、Maven 3.9+\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ8：为什么选择 Java + React + Python 三端架构？\u003c/b\u003e\u003c/summary\u003e\n\n每种技术选型都有明确的理由：\n\n- **Java 21 + Spring Boot（后端）：**\n  - 强类型 + 成熟的企业级生态，代码可维护性强\n  - Spring WebSocket 原生支持实时通信\n  - Virtual Thread（虚拟线程）天然适合多 Agent 并发执行\n  - 企业 IT 团队容易接受和部署\n\n- **React 18 + TypeScript（前端）：**\n  - 组件化开发，状态管理成熟（Zustand）\n  - TypeScript 提供类型安全\n  - Vite 构建速度快，开发体验好\n  - TailwindCSS 实现高效的 UI 开发\n\n- **Python FastAPI（分析服务）：**\n  - Python 生态在代码分析、AST 解析方面成熟\n  - FastAPI 异步性能好\n  - 作为独立服务，不影响主后端的稳定性\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ9：Docker 部署遇到问题怎么排查？\u003c/b\u003e\u003c/summary\u003e\n\n**容器启动后显示 unhealthy：**\n\n```bash\n# 查看容器状态\ndocker ps -a\n\n# 查看启动日志（Java 启动通常需要 30-60 秒）\ndocker logs zhikuncode\n\n# 查看健康检查详情\ndocker inspect --format='json .State.Health' zhikuncode | python3 -m json.tool\n```\n\n**常见启动失败原因：**\n- `LLM_API_KEY is not configured` — 未配置 API Key，请检查 .env 文件\n- `Unable to access jarfile` — 镜像构建不完整，尝试 `docker compose up --build`\n- 内存不足 — 默认需要 4GB，可在 docker-compose.yml 中调整 `deploy.resources.limits.memory`\n\n**查看运行时日志：**\n```bash\n# 实时跟踪日志\ndocker logs -f zhikuncode\n\n# 进入容器查看日志文件\ndocker exec -it zhikuncode ls -la /app/log/\ndocker exec -it zhikuncode tail -100 /app/log/app.log\n```\n\n**关于 `ALLOW_PRIVATE_NETWORK`：**\n\n此变量控制是否允许 Docker 桥接网络内的请求免认证访问。在 Docker 环境中默认为 `true`，因为容器网络本身已提供隔离。如需更严格的安全策略（如多租户环境），可设置为 `false`，此时所有非 localhost 请求都需要 Bearer Token 认证。\n\n**调整 JVM 内存：**\n\n在 `.env` 中设置：\n```bash\nJAVA_OPTS=-Xms512m -Xmx2048m --enable-preview\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eQ10：8080 端口被占用怎么办？\u003c/b\u003e\u003c/summary\u003e\n\n修改 `.env` 文件中的端口配置：\n\n```bash\nZHIKUN_PORT=9090  # 改为任意未被占用的端口\n```\n\n然后重新启动：\n```bash\ndocker compose down\ndocker compose up -d\n```\n\n访问 `http://localhost:9090` 即可。\n\n\u003c/details\u003e\n\n---\n\n## 🤝 贡献\n\n我们欢迎任何形式的贡献 —— Bug 修复、新功能、文档改进都可以。\n\n详见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n---\n\n## 📄 开源协议\n\n本项目使用 [MIT License](LICENSE) 开源协议。\n\n---\n\n## 📬 联系\n\n- **邮箱：** alizhikun@gmail.com\n- **GitHub Issues：** [提交问题](https://github.com/zhikunqingtao/zhikuncode/issues)\n\n---\n\n## ⭐ Star History\n\n如果这个项目对你有帮助，欢迎点个 Star ⭐\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#zhikunqingtao/zhikuncode\u0026Date\"\u003e\n    \u003cimg src=\"https://api.star-history.com/svg?repos=zhikunqingtao/zhikuncode\u0026type=Date\" alt=\"Star History Chart\" width=\"600\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e用 ❤️ 和 AI 构建\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhikunqingtao%2Fzhikuncode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhikunqingtao%2Fzhikuncode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhikunqingtao%2Fzhikuncode/lists"}