开源 AI 编程工作台 — 自托管，通过浏览器操作
Agent 分工与接续 · 上下文管理 · 工具授权 · 运行验证
快速开始 · 核心特性 · 案例展示 · 公开工程案例 · SWE-bench 评测 · CLI 工具 · skill技能系统 · 插件系统 · 可视化 · 记忆系统 · 竞品对比 · English
ZhikunCode 将多 Agent 分工、上下文管理、工具执行和运行验证接入同一个浏览器工作台。模型读取项目、修改文件、执行命令，工具结果进入下一轮判断；你可以跟进子任务、检查修改，在运行中补充要求、处理审批或取消任务。
运行环境由你部署，模型 API 由你选择。 任务覆盖代码开发与审查、网页和数据分析，以及 Word、Excel、PPT 等材料制作。先看下方公开成果，再按快速开始搭建，完成首次任务。模型 API 与外部服务仍会接收相应请求中的数据。
📱 手机实录：一条游戏需求 → 在线试玩 → Android 安装与实机操作 · 4 分 35 秒完整录屏，附在线游戏、开发介绍页、APK 及源码。
在线试玩《荣耀峡谷》 → · 下载游戏 Android APK →
🏗️ 查看完整系统架构图 →
Java Agent Runtime · React 浏览器操作面 · Python Capability Service · 全景可视化
🧭 查看完整能力总览 → 交互入口 · Agent / Run · 权限安全 · 工具与 Skill · 验证产物 · 观测恢复
历史代码规模快照（非当前版本统计）：
ea0170c· 2026-08-09 · Git 跟踪的产品源代码 134,826 行 / 863 文件（Java 93,118 / 622、React 33,642 / 209、Python 服务与 CLI 8,066 / 32；不统计本地忽略文件）
🔎 实时黄金监控：ZhikunCode vs Codex 同题 PK → ZhikunCode × Codex · 同一需求两套实现，14 维评分、过程截图与公开日志摘录
🚄 12306 候补全链路可视化：单文件零依赖交付 → ZhikunCode/KimiK3 × Codex/GPT-5.6 Sol · 7 维对比评估，附公开源码与 ZhikunCode 单文件演示
🎮 5小时 AI 从零写出可玩的《王者荣耀》网页版 → Kimi K3 · 一次连续开发 5 小时 29 分 · 19 个文件 / 7,979 行纯静态 Three.js · 打开浏览器即可试玩
📊 AI 办公工具对比测评（宇树科技 · 截至 2026-08-30）→ 五款工具 × 六任务连续链路 · 30 件固定终稿证据复核 · 同一报告阿里云 OSS 镜像：oss.zhikun.xin
🔍 AI Coding 代码审查对比：17 份报告 Claude Opus5.5：排名分析、方法与证据 → · GPT-6 Astra Ultra：公平排名与可复核证据 →
🔬 八款 AI Coding 同题代码审查（2026-09-25） → 八份原报告 · 六维评分 · 可复核证据与约1小时57分钟过程录屏
🏆 SWE-bench Lite 技术报告 →
提交命名空间20260525_zhikuncode· 历史 harness 结果 168 / 300 (56.0%)；公开轨迹存在参考修复暴露，评测边界见正文。
用手机浏览器操作部署在阿里云 ECS 上的 ZhikunCode，从一条需求出发，开发全新的王者荣耀风格 3D MOBA 单人游戏《荣耀峡谷》，随后发布在线试玩网址、生成开发过程可视化网页，再打包成 Android App，在手机上安装试玩。全程未调用 Skill，所需 Android 构建组件按需下载安装。
子任务达到轮次上限后，主 Agent 接管、修复问题并完成验证。 开发介绍页记录了 17 项 Vitest 测试、27 项浏览器检查通过。
观看完整实录 → · 在线试玩 → · 开发过程介绍 → · 下载 Android APK →
下载源码：网页游戏（ZIP）→ · Android 工程（ZIP）→
视频时间索引与文件校验
录制于 2026-10-28，时长约 4 分 35 秒，包含任务历史回看和现场安装试玩。录屏工作台显示的模型为 Kimi K3.1 Pro Highspeed。
| 时间（约） | 画面内容 |
|---|---|
| 00:00 | 手机浏览器回看游戏需求、工具执行与发布记录 |
| 00:49 | 打开开发过程可视化介绍页 |
| 01:20 | 打开在线游戏、选将和试玩 |
| 02:29 | 下载 APK，在手机上安装 |
| 02:54 | 启动已安装的 App，横屏操作游戏 |
| 03:31 | 返回工作台，查看任务导航、模型选项和主题 |
APK 内置游戏页面和资源，由 Android WebView 加载本地文件。
仓库原视频约 24.67 MiB，保留全部画面与音轨，未经重新压缩。SHA-256：
demo.mp4
38e6791000ebd7663a0144aaaa5be6a6e49c9c84fc8b695c58592a4a8380b29a
canyon-moba.apk
8d3cda9669bb39d3f95258a52f78fbd75b6aebf5699a66caa42db3c4f00128f5
canyon-moba-complete.zip
e0c5474537a23cc8081282eae4b33a9e2d951961ad51fbe59312b115a02df483
canyon-moba-android-source.zip
a37117559e5804f8de0a5b66b19b2679262050cbdd25398d5a64d7aab9c1a26b
zkcode 是 ZhikunCode 的手机部署版本。四段真实操作录像展示手机日历与照片、钉钉协作、短信发送与拨号，以及携程、淘宝和京东网页中的查询、筛选与人工接管。
打开完整展示页 → · 下载离线展示包（ZIP，35.6 MiB）→
点击封面查看对应演示，点击时间点定位到视频片段。四段录像共约 25 分 43 秒，均为静音版。
01 · 日历、照片与钉钉协作 播放完整视频 · 11:51 00:35 查询本机日历 |
02 · 短信发送与手机拨号 播放完整视频 · 02:27 |
03 · 携程航班查询、筛选与接管 播放完整视频 · 07:52 00:08 发起航班查询 |
04 · 淘宝购物车与京东搜索 播放完整视频 · 03:30 00:12 读取购物车商品 |
同一个实时黄金监控需求，分别交给 ZhikunCode 与 Codex 从零完成，再按需求理解、开发交互、数据准确性、架构、代码质量、用户体验等 14 个维度打分。报告同时保留双方的优点与缺陷。
- ZhikunCode：Kimi K3 遇到 HTTP 429 后，由用户切换至 GLM-5.2 并在同一逻辑会话中继续。
- Codex：GPT-5.6 Sol，推理强度 High。
- 最终评分 ZhikunCode 68.3、Codex 68.4，两者接近；截图为历史行情，银行价格含估算，全球数据覆盖仍有缺口。
查看对比报告 → · 下载原始数据 → · 了解评测方法 →
同一个"12306 候补成功后台全链路"动态可视化需求，分别交给 ZhikunCode 与 Codex 完成，从任务理解、代码质量、动态可视化、架构与数学、用户体验、开发效率、技术实现 7 个维度评估。报告同时保留双方的优点与缺陷。
- ZhikunCode：kimi-k3 交付单文件 HTML，1,061 行、零外部网络依赖，打开就能跑。
- Codex：GPT-5.6 Sol（高推理模式）交付 Next.js 工程，会话截图显示总耗时 27m52s。
- 最终加权评分 ZhikunCode 8.68、Codex 8.45，差距小于报告的 0.5 分区分阈值，不据此判断总体能力高低。
- 作品含 8 幕自动播放、13 节点关系图与 6 张数学原理卡；这是候补流程概念演示，图中架构与数值不是铁路系统内部资料或实测。
查看对比报告 → · 产物在线 Demo → · 下载原始数据 → · 了解评测方法 →
ZhikunCode 使用 Kimi K3 在 2026-08-09 的连续开发记录中完成一个纯静态 Three.js 5v5 MOBA 单机原型：5 名可选英雄、三路兵线、技能和装备，从选将、对线，到结算与重开。
- 首次请求至末次计费请求约 5 小时 29 分，产出 19 个第一方文件、7,979 行代码，另含 Three.js。
- 10 个子 Agent 分工，覆盖玩法、渲染、AI 行为与关卡资源；其中 9 个因预算或时限结束，未完成部分由主 Agent 接手。
- 纯静态交付，无后端、无外部网络依赖，浏览器直接运行。
- 公开材料包括代码、日志摘录、43 个 PNG 文件（42 个不同内容）及 5 段派生视频预览；预览不等于原始录屏。
具体如何调试： 浏览器运行状态显示约 100 个小兵聚集在地图拐角 (-80,60)；主 Agent 据此委派路径与分离逻辑修复，再运行长局检查。后续又定位并修复终局僵持、基地贴墙等问题。报告保留“运行取证→代码修改→复验”的记录，可用来核查分工和验证实际发生了什么。
查看详细案例 → · 在线试玩（5英雄选将）→ · 自动演示（直接进入对局）→ · 了解评测方法 →
五款 AI 办公工具——千问办公、Qoder、豆包办公、WorkBuddy 与 ZhikunCode——依次执行同一组六条连续指令，围绕宇树科技完成从 Excel 分析底稿、Word 研究报告、PPT 到信息图与交互 HTML 的完整办公链路，共产出 30 件固定终稿并逐件复核证据。
六任务等权评分 ZhikunCode 93.77、千问 93.57；投研实务权重评分 ZhikunCode 92.65、千问 93.32，两榜均处于近分组。ZhikunCode 六件终稿均为 G1，需修正后采用。这是单次固定样本、不同模型条件下的产物评测，不外推为产品总体排名。
查看完整报告（GitHub Pages）→ · 阿里云 OSS 镜像 →
与 WorkBuddy 完成同题教学材料，检查文档结构、25 页课件、配图和要求落实情况；这是固定产物比较，不代表教学效果评估。查看产物对比。
两位评估者分别分析同一组报告，保留方法与证据；不是两组独立产品试验。
Claude Opus5.5：排名分析方法、过程、证据与结论 → · GPT-6 Astra Ultra：公平排名与可复核证据 →
八款 AI Coding 工具审查同一代码提交，从有效发现、准确性、归因、证据、工程覆盖及建议交付六个维度比较最终报告。公开八份原报告、逐项评分、独立复核证据、重算脚本与约1小时57分钟的过程录屏。本次为单任务产物评测，不代表产品总体能力排名。
评测首页 → · 证据与复算 → · 过程录屏与时间索引 →
ZhikunCode 在八方审查中找到工具输出 outputTruncated 与上层读取 truncated 的字段错配，并排除一项工作目录丢失的误报；复核也保留其自身漏检和错误建议。查看具体发现。
以上案例的模型、输入和验收条件不同。详细方法与数据见各报告；公开材料范围及文件校验见证据说明。
| 特性 | 说明 | |
|---|---|---|
| 🌐 | 浏览器全流程操控 | 部署一次，任何设备的浏览器即可完成全流程操作 —— 权限审批、方案协商、任务管控，手机上也能用，无需安装客户端 |
| 🧭 | 开发工作台与过程显示 | 开发工作台展示对话、工具、文件、Git、终端、浏览器与 Agent 信息；精简、标准、完整过程三档控制过程展示。“本轮修改”可检查已记录的成功原生 Edit／Write；简洁视图切换入口目前隐藏 |
| 📦 | 当前交付投影 | 后端按 Root Run 及递归子 Run 关联本轮要求、回复、产物、待处理交互与证据；旧会话无法精确关联时采用兼容回退。这是运行数据组织能力，不代表简洁视图切换已开放 |
| 🔀 | 会话资料合并 | 将 2～5 个空闲会话的摘要、已持久化过程文本和可确认归属的临时产物整理到一个新会话，保留来源会话；新会话等待下一条指令，不自动合并工程代码 |
| 📁 | Project 与 Run 控制 | 直连本机可选用原生目录选择器，远程部署只浏览配置的 allowed roots；Project 经真实路径规范化并持久授权，Session 拒绝客户端任意 workingDirectory。运行中输入按 Session 投递并返回 queued/applied/rejected，支持取消、包含 INTERRUPTED 的 CAS 单一终态与 WebSocket 恢复 |
| 🔗 | 引用本地文件 | 直连本机通过系统选择器把 canonical 路径加入提示词（不上传内容）；ECS、远程或代理访问通过浏览器选择文件，立即上传为 OSS 永久公开对象，再把地址加入提示词。远程上传需要先配置 OSS |
| 🤖 | Agent 委派与后台任务 | 五种子 Agent 角色、独立上下文与并行执行；同步结果回传、当前 Run 后台结果汇总，以及可查询、可请求取消的后台任务 |
| 🔒 | 统一授权安全架构 | 所有核心工具统一经过 Tool Gateway：规范化输入冻结 → Operation Analyzer 风险与资源分析 → 系统不变量检查 → RUN/SESSION/WORKSPACE Grant 匹配或持久权限交互 → 执行前动态复检 → 结构化结果审计。高风险操作只允许单次授权；专用 Network/MCP Analyzer 对 SAFE/GUARDED 操作支持按工具记住 RUN/SESSION 授权，未知 MCP/动态工具默认只能单次审批 |
| 🇨🇳 | 国产大模型直连 | 可同时配置千问 / DeepSeek / Moonshot / 智谱GLM / MiniMax 等渠道，使用各自的 Key、端点和可用模型 |
| 🐳 | Docker 一键部署 | docker compose up -d 默认启动 Java 后端和内置静态前端；镜像同时包含可选的受管 Python 服务，数据存本地 |
| 📤 | OSS 发布与截图粘贴（可选） | 按明确指令发布工作区文件；有匹配 Manifest 时复检验证状态和哈希。粘贴截图在 OSS 可用时立即上传，否则用 Base64；远程文件引用会上传永久公开对象，详见配置说明 |
| 🌍 | 秒悟应用发布（可选） | 通过 /publish-meoo 将已验证的静态网站或全栈应用发布为独立新站点，获取可分享的网站链接；默认关闭，发布按当前权限模式授权或拒绝 |
| 🎙️ | 语音交互（ASR / TTS） | 对话输入支持麦克风语音识别（qwen3-asr-flash），AI 回复支持一键朗读（qwen3-tts-flash）；接入阿里云百炼 DashScope，配置 API Key 即用，未配置时自动隐藏 |
| ⚡ | 上下文管理与恢复 | 裁剪旧工具输出、渐进折叠、摘要压缩与上游上下文拒绝后的分级恢复；图片外置引用、按需注入和预算守卫减少历史图片负担。自纠错循环与精确 tokenizer 为默认关闭的可选增强 |
| 📷 | 多模态图片对话 | 支持上传或粘贴图片。当前模型不支持图片时，依次尝试配置的兜底模型、模型家族、同 Provider 和其他已配置视觉模型；没有可用目标时不能保证兜底。外置图片引用重新注入时，单次最多 8 张，Base64 单张上限 1,500,000 字节、总量上限 2,000,000 字节；实际还受模型支持图片数和剩余预算约束。图片引用、完整性检查与预算限制见 ImageRefInjector / TokenBudgetGuard |
| 🖼️ | 浏览器语义快照 | /snap 命令智能捕获网页完整状态（DOM 结构 + 交互元素），支持富交互页面语义提取，生成结构化 JSON 供 Agent 解析和回放验证 |
| 💬 | 轮次与任务过程视图 | 显示方式三档：精简档默认折叠问题、过程与回复，可分别展开；标准、完整过程档保留完整问题与回复，按档展示过程，运行中同样生效。移动端常驻输入卡片提供附件、语音和显示方式切换，首页模板可直接填入草稿。 |
| 📊 | 实时活动追踪与审批 | Activity Panel 实时记录 AI 工具执行全流程，L1/L2/L3 三层展示体系，Signal 智能标记（auto_approve/review_recommended/needs_review），一键批量审批决策，SQLite 后端持久化，支持会话恢复 |
| 🧪 | 运行时验证框架（Runtime Verification） | browser／http_api 两类验证器及 auto 自动选择 + 8 种 HTTP action handler + JSONPath 断言 + 证据链 SQLite 存储 + Feature Flag 双重门控 + 前端实时进度面板 |
| 🔍 | 证据包查看 | 查看验证步骤及实际留存的截图、命令、控制台、测试、视频、HAR、diff 等证据类型；类型定义不保证每次都产出。移动证据审批仍有未接通链路 |
| 🏆 | SWE-bench Lite 历史记录 | 2026-05、qwen3.7-max、六工具、无子 Agent；历史 harness 结果 168/300。公开轨迹存在参考修复暴露，不能无条件视为独立完成率，详见评测正文 |
| 🚀 | 工程测试与观测 | 仓库提供后端、前端、Python 测试和 CI；历史接口延迟属于特定环境采样，不是模型完成任务耗时，也不代表当前版本全部测试通过 |
| 🏭 | 运行时可靠性 | Run 状态 CAS 原子管理 · 完整 Session 快照、Run event sequence 与待处理持久交互重放 · 进程硬超时+梯度终止 · 作用域 Grant 与子 Agent 受控继承 · Artifact declare→seal→hash 验证及显式发布 · 结构化工具结果生成工具卡片与权威下载链接 · sid/rid/prid/agent/turn/tool/llm 日志关联 · BestEffortObservabilityRecorder 补充事件失败隔离 · Provider 本地预算守卫 |
支持浅色、深色、液态玻璃、星舰、花果晨、灵霄夜、果冻、蜘蛛爬虫和璀璨银河九套主题。桌面端通过顶栏「外观设置」切换，手机布局通过输入区「更多操作」中的「外观」切换；设置即时生效并保存在本地。
蜘蛛爬虫（spider）采用深黑底与青色／洋红／紫色霓虹蛛网，八足蜘蛛在空闲时探索、抓取文字副本，并随真实任务状态变化调整动作。选中即启用完整动效，不提供独立动效档位；原始文字仍可选择和复制。
该主题优先适配 PC，平板和手机按可用空间减少同时抓取数量。三维动效需要 WebGL 2，不可用时保留主题配色与聊天功能，页面隐藏时暂停三维绘制。相比普通主题会增加 GPU 开销；动画本身不额外调用模型。
璀璨银河（galaxy）以持续旋转的蓝／紫／玫红银河铺满页面，真实任务通过文件星点、工具光轨和回复星尘联动；工具详情折叠时，光效可落在执行摘要上。选中即启用完整效果，不提供独立效果开关，也不增加星图侧栏；原始文字和操作保持原位。动效需要 WebGL 2，不可用时保留静态配色与聊天功能，页面隐藏时暂停绘制。相比普通主题会增加 GPU 与电量消耗；动画本身不额外调用模型，历史消息不会重播任务动画。
果冻提供浓郁／克制样式及完整、精简、关闭三档动效，并遵循系统「减少动态效果」偏好。
花果晨与灵霄夜采用大闹天宫重彩戏曲风，分别提供暖色绢纸与深色夜景配色；使用专属强调色，不开放强调色预设切换。两套主题均提供：
- 浓郁／克制：开启「浓郁模式」展示描金纹样、牌匾和实色消息气泡，关闭后使用克制样式；动效可独立选择完整、精简或关闭。
- 闭关：收起装饰层，专注书写。
- 装裱分享：将会话题名与可编辑的题跋制作成立轴、手卷或册页样式的单张 PNG 图片并导出。
新建会话默认使用开发工作台、标准显示方式，显示方式可选精简、标准、完整过程；简洁工作台的切换入口目前隐藏。助手回复末尾的“本轮修改”可展开文件清单，查看本轮原生 Edit／Write 的逐次修改（仅含成功且路径可核实的操作）。
在会话列表选择 2～5 个已停止执行的空闲会话（可来自不同文件夹）合并为新会话，需确认主会话、新标题和模型；新会话接收交接摘要、过程文本与可确认归属的临时产物副本，工程代码不自动合并。合并期间来源会话可查看但不能执行或删除；新会话使用**“完全访问权限”（AUTO_APPROVE）**模式，创建后等待你的下一条指令。
语音识别需配置 LLM_PROVIDER_DASHSCOPE_API_KEY（不能用 Token Plan Key），热词纠正在根目录 .env 设置 ASR_CORRECTIONS 后重启后端生效。格式为 标准写法:变体1,变体2;标准写法2:变体3，例如 zhikuncode:zhi kun code,zkun code,智坤code;PostgreSQL:post gre sql。配置项见 .env.example。
准备支持工具调用的模型 API Key，可从阿里云百炼、DeepSeek、Moonshot/Kimi或其他支持的渠道获取。普通 DashScope 与 Token Plan Key 不能混用；费用、额度和账号权限以所选服务为准。
首次使用时，登录所选服务商的平台，在 API Key 管理页创建密钥并复制保存；在下方克隆仓库并执行 cp .env.example .env 后，将其填入 .env 中对应渠道的变量（例如 LLM_PROVIDER_DASHSCOPE_API_KEY）。将未使用渠道的 API Key 值清空，不要保留 your-…-key 示例值。不要提交含密钥的 .env。
准备一个支持工具调用的模型 API Key。以下命令面向 macOS／Linux 的 Bash 或 Zsh；Docker 还需 Docker Engine、Compose V2 和能下载构建依赖的网络。
| 方式 | 本次能体验什么 | 入口 |
|---|---|---|
| Docker 基础部署 | 对话、文件修改、命令和测试；镜像含前端与 Node，无需宿主安装 Java、Node | 下方命令 → 首次任务 |
| 本地三服务 | 开发调试、完整前端代理，以及依赖就绪的 Python 分析／浏览器能力 | 本地安装 → 首次任务 |
Docker 入口检查 OpenAI、DashScope、Token Plan、DeepSeek、Moonshot、Zhipu、ZenMux 或旧式 LLM_API_KEY；仅有 Kimi Code、MiniMax、OpenRouter 专用 Key 时会在入口退出，请使用本地三服务路径。基础部署在本机构建镜像，不是拉取预构建应用镜像。
git clone https://github.com/zhikunqingtao/zhikuncode.git
cd zhikuncode
cp .env.example .env
# 编辑 .env，填写自己的 Key，例如 LLM_PROVIDER_DASHSCOPE_API_KEY
# 设置 WORKSPACE_PATH=/你的项目绝对路径；目录需存在且允许容器用户读写
docker compose up -d --build
docker compose ps
curl -fsS http://localhost:8080/actuator/health已有 .env 时保留自己的配置。健康检查应包含 "status":"UP"；打开 localhost:8080，选择模型并授权容器内 /app/workspace 下的项目。端口改动需按 .env 中 ZHIKUN_PORT 同步访问；启动失败看 docker compose logs --tail=100 zhikuncode。停止用 docker compose stop，保留数据时不要使用 down -v。
新会话默认完全访问（AUTO_APPROVE）；需要审批时先切换权限模式。基础 Compose 不启动 Python，相关验证能力见可选配置。默认容器入口会放行到达后端的来源，首次试用应在受控网络，远程部署先处理访问边界。
本地三服务：依赖、三终端启动与健康检查
准备 JDK 21、Node.js 22.x（至少 22.13）或 24+、Python 3.11 或 3.12、Git、curl、ripgrep；Java 构建使用仓库自带 Maven Wrapper。先按上方步骤获取源码并配置 .env，确认 8080／8000／5173 端口未被其他服务占用。从仓库根安装依赖：
python3.11 -m venv python-service/.venv
python-service/.venv/bin/python -m pip install -r python-service/requirements.lock
python-service/.venv/bin/python -m playwright install chromium
npm --prefix frontend ci使用 Python 3.12 时替换首行解释器。Linux 按 Playwright 输出补齐 Chromium 系统库；文件类型检测可能需要 libmagic。下面显式使用 .venv，避免把依赖装进与运行时不同的环境。
打开三个终端，每个终端都从仓库根目录开始，先执行公共配置：
set -a
source .env
set +a
export ZHIKUN_DEFAULT_WORKSPACE="$PWD"
export WORKSPACE_ROOT="$PWD"
export ZHIKUN_LOCAL_PICKER_ENABLED=true
export PATH="$PWD/scripts/mcp:$PATH"只加载自己维护的可信 .env。本机 picker 适用于直连本机；远程部署保持关闭并配置 allowed roots。然后分别执行：
# 终端一：Java 后端，Python 在另一个终端独立运行
export PYTHON_SERVICE_AUTO_START=false
cd backend
./mvnw spring-boot:run -DskipTests# 终端二：Python 能力服务
export PYTHONPATH="$PWD/python-service/src"
python-service/.venv/bin/python -m uvicorn src.main:app --app-dir python-service --host 127.0.0.1 --port 8000# 终端三：前端开发代理
cd frontend
npm run dev在另一个终端检查：
curl -fsS http://127.0.0.1:8080/actuator/health
curl -fsS http://127.0.0.1:8000/api/health
curl -fsS http://127.0.0.1:8000/api/health/capabilities
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5173/Java 应为 UP，Python 为 ok，前端 HTTP 为 200；能力列表还需检查各域的 available 与 reason。打开 localhost:5173 后继续首次任务。各终端按 Ctrl+C 停止自己的服务。
依赖准备后也可使用 ./start.sh，但它会清理固定端口、终止匹配的旧 Java 进程并删除 backend/target；脚本优先使用 python-service/venv，其次 .venv，最后系统 Python。共享开发机优先采用上面的手动方式。Vite 开发代理只供本机使用，不应直接暴露到远程网络。
新建会话并选择、授权服务端项目目录，然后选择模型并描述任务。开发工作台提供文件、Git、终端、浏览器及 Agent 视图；助手回复末尾的“本轮修改”展示已记录的成功原生 Edit／Write。目录在 Docker 中使用 /app/workspace 下的路径；远程后端不能直接读取客户端电脑上的本地路径。“在文件夹中显示”仅适用于支持该操作的直连本机环境。
Docker 可选：启用容器内 Python 能力服务
基础镜像包含 Python 环境，默认未启动。以下从仓库根通过标准输入传入 override；以后重新创建容器时也需要保留这组覆盖设置：
docker compose -f docker-compose.yml -f - up -d --build <<'YAML'
services:
zhikuncode:
environment:
PYTHON_SERVICE_AUTO_START: "true"
PYTHON_SERVICE_PATH: /app/python-service
PYTHON_SERVICE_EXECUTABLE: /app/python-service/.venv/bin/python
WORKSPACE_ROOT: /app/workspace
YAML
docker compose exec zhikuncode curl -fsS http://127.0.0.1:8000/api/health/capabilities这条路径使 Java 能调用容器内 Python，仍需检查 Feature Flag 和实际能力状态。前端直连 Python 的文件／Git／分析界面还需同源代理，不能只开进程就视为全部界面就绪。代理范围以 Vite 配置与 Python 路由为准；保留 Java 的文件选择、引用和搜索入口，并让 Java、Python 与 WebSocket 共用访问控制。不要直接公开 Python 端口。
首次任务：准备两个文件，让模型改代码，再独立验收
本练习不安装第三方包。先保留一个专用终端；从 zhikuncode 仓库根目录执行下面的准备命令，创建独立临时项目（两种部署方式共用）：
ZHIKUN_DEMO=$(mktemp -d "${TMPDIR:-/tmp}/zhikuncode-first-task.XXXXXX")
mkdir -p "$ZHIKUN_DEMO/src" "$ZHIKUN_DEMO/test"
cat > "$ZHIKUN_DEMO/src/shipping.mjs" <<'JS'
/** Amounts are in yuan. Existing rule: free shipping at 100, otherwise 6. */
export function shippingFee(subtotal) {
if (!Number.isFinite(subtotal) || subtotal < 0) {
throw new RangeError('subtotal must be a finite, non-negative number');
}
return subtotal >= 100 ? 0 : 6;
}
JS
cat > "$ZHIKUN_DEMO/test/shipping.test.mjs" <<'JS'
import test from 'node:test';
import assert from 'node:assert/strict';
import { shippingFee } from '../src/shipping.mjs';
test('regular: zero subtotal costs 6', () => assert.equal(shippingFee(0), 6));
test('regular: below 100 costs 6', () => assert.equal(shippingFee(99.99), 6));
test('regular: exactly 100 is free', () => assert.equal(shippingFee(100), 0));
test('regular: above 100 is free', () => assert.equal(shippingFee(150), 0));
test('member: below 80 costs 6', () => assert.equal(shippingFee(79.99, true), 6));
// These two acceptance tests intentionally fail before the first task is done.
test('member: exactly 80 is free', () => assert.equal(shippingFee(80, true), 0));
test('member: below 100 is free', () => assert.equal(shippingFee(99.99, true), 0));
test('member: at 100 remains free', () => assert.equal(shippingFee(100, true), 0));
test('negative subtotal is rejected', () => assert.throws(() => shippingFee(-1), RangeError));
test('NaN subtotal is rejected', () => assert.throws(() => shippingFee(NaN), RangeError));
test('Infinity subtotal is rejected', () => assert.throws(() => shippingFee(Infinity), RangeError));
test('-Infinity subtotal is rejected', () => assert.throws(() => shippingFee(-Infinity), RangeError));
JS本地三服务用户在同一终端继续；需要 Node.js 22+：
git -C "$ZHIKUN_DEMO" init -q
git -C "$ZHIKUN_DEMO" add .
ZHIKUN_BASE=$(git -C "$ZHIKUN_DEMO" write-tree)
(cd "$ZHIKUN_DEMO" && pwd -P && node --test test/shipping.test.mjs)Docker 用户在同一终端继续；使用容器自带 Node，不要求宿主安装 Node。第一行需成功确认挂载可写：
docker compose exec -T zhikuncode sh -c 'test -w /app/workspace'
ZHIKUN_CONTAINER_DEMO=$(docker compose exec -T zhikuncode mktemp -d /app/workspace/first-task.XXXXXX)
tar -C "$ZHIKUN_DEMO" -cf - src test | docker compose exec -T zhikuncode tar -C "$ZHIKUN_CONTAINER_DEMO" -xf -
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git init -q
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git add .
ZHIKUN_BASE=$(docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git write-tree)
printf '%s\n' "$ZHIKUN_CONTAINER_DEMO"
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode node --test test/shipping.test.mjsgit write-tree 将初始文件快照的 tree ID 保存到 ZHIKUN_BASE，不创建提交；后续即使索引改变，仍与这份固定快照比较。保留当前终端及变量供验收使用。初始应是 10 通过、2 失败，退出码 1；失败项为 member: exactly 80 is free 与 member: below 100 is free。若出现其他错误，先处理环境。
打开工作台，新建会话并授权打印出的项目路径。本地使用 pwd -P 的路径，Docker 使用 /app/workspace/first-task.…；选择支持工具调用的模型，发送：
这是独立的运费规则练习项目。阅读 src/shipping.mjs 和 test/shipping.test.mjs，
先运行 node --test test/shipping.test.mjs 确认当前失败。
只修改 src/shipping.mjs，实现 shippingFee(subtotal, isMember = false)：
普通用户满100元免运费，否则6元；会员满80元免运费，否则6元。
不传第二个参数时保持普通用户行为；负数或非有限金额仍抛出 RangeError。
不要改测试，不安装依赖，不联网，不提交或推送。
修改后重新运行测试并检查 git diff，报告实际结果和改动文件；未执行的检查明确说明。
在工具卡片中查看实际读写和命令输出。完成后，本地用户回到原终端独立验收：
(cd "$ZHIKUN_DEMO" && node --test test/shipping.test.mjs)
git -C "$ZHIKUN_DEMO" diff "$ZHIKUN_BASE" -- src/shipping.mjs
git -C "$ZHIKUN_DEMO" diff --name-only "$ZHIKUN_BASE"
git -C "$ZHIKUN_DEMO" diff --exit-code "$ZHIKUN_BASE" -- test/shipping.test.mjs
git -C "$ZHIKUN_DEMO" ls-files --others --exclude-standardDocker 用户在原仓库终端验收容器中的同一个项目：
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode node --test test/shipping.test.mjs
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git diff "$ZHIKUN_BASE" -- src/shipping.mjs
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git diff --name-only "$ZHIKUN_BASE"
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git diff --exit-code "$ZHIKUN_BASE" -- test/shipping.test.mjs
docker compose exec -T -w "$ZHIKUN_CONTAINER_DEMO" zhikuncode git ls-files --others --exclude-standard验收终点：12 通过、0 失败；相对固定基线的 diff 只有 src/shipping.mjs，测试文件无变化；检查未跟踪文件，区分应用元数据与额外业务文件。这验证基本改码与测试流程，不代表已经验证并行 Agent、浏览器或发布能力，也不是模型成绩保证。
ZhikunCode 提供 /publish-oss 命令，将工作区内单个普通文件发布为 OSS 永久公开链接。底层发布能力默认关闭，需单独配置启用；部署未启用时，命令不出现在命令列表和补全中。匹配到同一持久化根 Session 及后代 Run 的 Manifest 时，要求状态为 verified／partial、目标条目已验证且哈希仍匹配；未匹配 Manifest 时允许按工作区文件路径发布，仍检查路径、文件类型、大小及敏感内容。生成、预览文件不会自动发布，但下述截图粘贴和远程引用有独立的即时上传路径。发布必须由用户明确请求；AUTO_APPROVE 可自动授权，PLAN 和 DONT_ASK 拒绝这类高风险发布，其余权限模式要求单次确认。配置、文件和内容检查仍须通过。
启用同一套 OSS 配置后，浏览器还能感知从其他应用复制并粘贴到对话框的 PNG/JPEG/WebP 截图（单张不超过 5 MiB），通过固定后端通道立即上传，并将服务端验证过的 OSS 图片地址直接交给视觉模型。这个路径不调用 /publish-oss Skill，也不额外调用 LLM；OSS 未配置时自动降级为 Base64 直传，无需额外配置即可使用图片分析能力。
“引用本地文件”会按实际访问能力选择路径：只有直接 loopback、无代理转发且原生选择器安全门禁全部满足时，才只发送 canonical 路径；ECS、远程和代理访问则使用浏览器文件选择器，选中后立即上传到 ${ZHIKUN_OSS_PREFIX}/local-files/，并把文件名与 OSS 地址加入提示词。远程文件默认沿用 ZHIKUN_OSS_MAX_FILE_BYTES（1 GiB）上限，OSS 未配置时该入口不可用且不会降级为 Base64。该通道接受任意文件类型，不执行敏感文件名或内容扫描；对象发布为永久 public-read，移除标签、切换 Session 或放弃消息都不会删除它，使用前请确认文件可以公开。
凭证模式默认为 auto：本机存在完整的标准 ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET 时优先使用阿里云默认凭证链；否则，配置了 ZHIKUN_OSS_ECS_ROLE_NAME 时使用 ECS RAM Role + IMDSv2；两者都没有时仍尝试默认凭证链（例如阿里云 CLI 默认 Profile）。因此同一套非密钥配置可同时支持本地一键启动和 ECS。每个部署者都必须使用自己的 Bucket 与最小权限身份；仓库不包含维护者的 OSS 凭证。
在 .env 中配置：
ZHIKUN_OSS_ENABLED=true
ZHIKUN_OSS_ENDPOINT=https://oss-cn-your-region.aliyuncs.com
ZHIKUN_OSS_REGION=cn-your-region
ZHIKUN_OSS_BUCKET=your-bucket
ZHIKUN_OSS_PUBLIC_BASE_URL=
ZHIKUN_OSS_PREVIEW_ENABLED=false
ZHIKUN_OSS_PREFIX=zhikuncode-artifacts
ZHIKUN_OSS_ECS_ROLE_NAME=your-ecs-ram-role
ZHIKUN_OSS_CREDENTIAL_MODE=auto
ZHIKUN_OSS_MAX_FILE_BYTES=1073741824
ZHIKUN_OSS_CONNECT_TIMEOUT_MS=10000
ZHIKUN_OSS_REQUEST_TIMEOUT_MS=120000可选自定义域名与预览：先自行完成目标 Bucket 的域名绑定、DNS 和 HTTPS 配置，再将 ZHIKUN_OSS_PUBLIC_BASE_URL 设为自己的 HTTPS 域名根地址（例如 https://files.example.com，不带端口、路径前缀、查询参数或片段）。产物发布、截图粘贴和远程文件引用会统一使用该域名，上传 Endpoint 不变。设置 ZHIKUN_OSS_PREVIEW_ENABLED=true 后，仅新上传的 HTML、纯文本、PDF、PNG/JPEG/GIF/WebP 使用 inline，其他类型仍作为附件；开启预览必须配置自定义域名，不能使用 OSS 默认域名。默认留空且关闭时保持原下载行为。
OSS 关闭时，无效的自定义域／预览配置会产生警告并从 CSP 省略，不阻断启动；开启时仍会阻止启动。合法自定义域在 OSS 关闭时仍保留在 CSP 中，以支持历史图片。发布入口始终保留严格配置校验。剪贴板 API 会规范化 HEAD 返回的具体图片 MIME（统一大小写、去除参数），保留有效 CDN 转码类型；其他类型回退到文件字节检测结果。客户端声明的图片类型仍须匹配上传内容。
本地部署可先配置阿里云 CLI 默认 Profile；也可将受限 RAM 用户或临时 STS 的 ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET 与可选 ALIBABA_CLOUD_SECURITY_TOKEN 写入本机 .env。不要提交真实值。旧式 OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_SESSION_TOKEN 会被拒绝。
身份只应具有目标 Bucket/前缀所需的最小
PutObject、GetObject/HeadObject、PutObjectAcl和失败清理DeleteObject权限；Bucket 必须允许目标对象设置public-read，否则上传会失败并尝试清理私有对象。
使用流程：
- 在已授权项目中准备要发布的单个文件并检查内容。有匹配 Manifest 时，目标条目必须已验证且哈希一致；没有 Manifest 时按工作区文件策略检查。
- 明确输入
/publish-oss <文件路径>，或说明“上传刚生成的产物到 OSS”。 - 先确认文件和公开范围；如当前权限模式要求审批，核对卡片后决定是否批准。
AUTO_APPROVE可自动通过权限裁决。 - 上传成功后使用发布成功卡片打开预览或下载；以浏览器实际响应为准，不让模型重新拼接链接。
安全边界与当前限制：
- 只发布 workspace 内单个普通文件，默认及最大上限为 1 GiB（1,073,741,824 字节），可通过
ZHIKUN_OSS_MAX_FILE_BYTES设置更小上限；已有显式配置不会自动提高。有匹配 Manifest 时复核其归属、条目状态和哈希。无 Manifest 的工作区文件回退不等于已经做过运行验证。 - 拒绝目录、批量上传、符号链接、workspace 外路径、
.env、私钥、数据库、凭证配置及检测到敏感内容的文件。 - 对象先私有上传，远端校验成功后才切换为
public-read；失败时清理本次新建的私有对象。 - 返回地址为永久公开链接。卡片依据公开地址的响应判断预览或下载；检查失败时保守显示“下载”，不会撤销已成功的发布。OSS 默认域名通常会下载 HTML。
- 旧对象的内容、元数据及历史消息链接不会迁移；重复发布旧对象可返回当前配置域名，但原附件仍可能下载。关闭预览也不会恢复已上传对象的元数据。
- HTML 预览会执行页面脚本。分享域不得共享应用登录 Cookie 或加入应用认证接口的跨域白名单；同站子域名不等于完整安全隔离。注意 HTTPS 证书续签，不承诺所有浏览器均可预览所有格式。
- 当前精简版不提供批量发布、发布历史或撤销入口；删除公开对象需要运维人员在 OSS 侧显式执行。
- 本地与 ECS 都支持真实上传；本地使用默认凭证链，ECS 建议使用自动轮换的 RAM Role 临时凭证。
- 远程文件引用使用原始请求体流式上传，不扩大 Spring 的全局 multipart 限制；若 ECS 前还有反向代理，代理的请求体上限也必须不低于
ZHIKUN_OSS_MAX_FILE_BYTES。
秒悟 /publish-meoo 的策略不同：要求绑定实际通过的 VerifyJourney 证据、项目目录、运行方式和发布快照，发布前复检；每次创建新站点并消耗平台额度。配置与步骤见秒悟发布指南。
ZhikunCode 支持多 Provider 同时配置（推荐）和单 Provider 两种模式。多 Provider 模式下可在前端自由切换模型：
方式一：多 Provider 配置（推荐）
在 .env 中为要使用的服务商填写独立的 API Key，未使用渠道的 Key 值留空；以下为配置示例，前端可切换已配置的模型：
# DashScope（千问系列）
LLM_PROVIDER_DASHSCOPE_API_KEY=your-dashscope-key
# DashScope Token Plan（百炼订阅专属 sk-sp- Key，与按量计费 Key 分离）
LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_API_KEY=your-token-plan-key
# DeepSeek
LLM_PROVIDER_DEEPSEEK_API_KEY=your-deepseek-key
# Moonshot (Kimi)
LLM_PROVIDER_MOONSHOT_API_KEY=your-moonshot-key
# Kimi Code 订阅：K3.1 Pro Highspeed + K2.8 Preview（与 Moonshot 按量渠道独立）
LLM_PROVIDER_KIMI_CODE_API_KEY=your-kimi-code-key
# LLM_PROVIDER_KIMI_CODE_MODELS=k3.1-pro-highspeed,kimi-for-coding
# Zhipu (智谱 GLM)
LLM_PROVIDER_ZHIPU_API_KEY=your-zhipu-api-key-here
# MiniMax
LLM_PROVIDER_MINIMAX_API_KEY=your-minimax-api-key-here
# ZenMux（默认目录：Fable 5.1 / Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / GPT-5.6 Sol / GPT-6 Astra / Gemini 4 Argon / Grok 4.7 / Muse Wonder 1.0）
# 支持逗号分隔多 Key：订阅 Key（sk-ss-v1- 前缀）放前优先、按量 Key（sk-ai-v1- 前缀）兜底；
# 402 quote_exceeded / 404 model_not_available 时自动冷却 15 分钟切换到下一把 Key。
LLM_PROVIDER_ZENMUX_API_KEY=your-zenmux-api-key-hereKimi Code 订阅： 配置独立的 LLM_PROVIDER_KIMI_CODE_API_KEY 后，仓库默认注册 k3.1-pro-highspeed 与 kimi-for-coding，请求端点为 https://api.kimi.com/coding/v1；Moonshot 按量渠道默认 kimi-k3.1-pro-highspeed，密钥、模型 ID 与路由分开，不自动跨渠道切换。订阅模型的流式与非流式请求均显式发送 thinking.type=enabled、reasoning_effort=max。注册表声明 1,048,576 token 上下文和 131,072 token 输出上限，主循环推荐输出预算另按 65,536 token 上限裁剪；这是应用配置，不代表账号必然有相应权限。订阅用量不按 Moonshot 按量价格估算，界面估算为 0 不代表免费。仅配置 Kimi Code Key 仍会被当前 Docker 入口检查拒绝，先采用本地开发路径。历史案例的 Kimi K3 保持原记录。模型资料参见 Kimi Code 官方模型文档。
GLM-5.3（百炼）： 复用 LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_API_KEY，默认模型列表已包含 bailian/glm-5.3；若 .env 自定义了 LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_MODELS，请将该 ID 加入列表并重启。内部模型 ID 为 bailian/glm-5.3，仅发往百炼 Token Plan 的请求使用上游 ID glm-5.3，现有 glm-5.3 仍走智谱直连。百炼配置中填写裸 glm-5.3 也会自动规范化并去重，避免注册顺序影响路由。流式与非流式均固定 enable_thinking=true、reasoning_effort=max、clear_thinking=false，配置最大 1,000,000 tokens 上下文和 65,536 tokens 单次输出预算（已实测接受的应用预算，非官方最大输出声明）；支持工具调用与历史思考回传，文本模型不开放图片输入。订阅 Credits 以百炼账单为准，界面 0 单价不代表免费。2026-09-21 核对：Token Plan 支持模型、GLM 参数、官方上下文配置。
方式二：单 Provider 配置（向后兼容）
使用单 Provider 模式时，先清空 .env 中所有 LLM_PROVIDER_*_API_KEY 的值，再配置 LLM_BASE_URL 和 LLM_API_KEY；系统在未配置多 Provider 时自动回退：
| 服务商 | Base URL | 推荐模型 | 备注 |
|---|---|---|---|
| 千问/DashScope | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen3.8-max-0902 | 按量计费 Provider，国内直连 |
| 阿里云百炼 Token Plan | https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 |
qwen3.8-max / qwen3.8-flash / deepseek-v4.1-flash | 使用独立 sk-sp- Key；模型均标注“百炼”。V4.1 Flash 为服务端 app.model.default、快速查询及图片兜底的默认值；前端初始模型偏好仍为 qwen3.8-max-0902，用户配置／会话选择优先 |
| DeepSeek | https://api.deepseek.com/v1 |
deepseek-flash | 国内直连；DeepSeek V4.1 Flash，支持思考、工具调用与原生视觉 |
| Moonshot（Kimi） | https://api.moonshot.cn/v1 |
kimi-k3.1-pro-highspeed | 独立 Moonshot 按量 Key；当前注册表配置视觉和 1M 上下文 |
| Zhipu（智谱 GLM） | https://open.bigmodel.cn/api/paas/v4 |
glm-5.3, glm-5.3-flash | 国内直连 |
| MiniMax | https://api.minimax.chat/v1 |
MiniMax-M3 | 百万上下文 |
| ZenMux（多模型中转） | https://zenmux.ai/api/v1 |
anthropic/claude-fable-5.1 / anthropic/claude-opus-5.5 / anthropic/claude-sonnet-5.5 / anthropic/claude-haiku-5.5 / openai/gpt-5.6-sol / openai/gpt-6-astra / google/gemini-4-argon / x-ai/grok-4.7 / meta/muse-wonder-1.0 | OpenAI/Google/xAI/Meta 模型使用 Responses 推理与工具续轮；支持图片 |
| OpenAI | https://api.openai.com/v1 |
gpt-5.6-sol / gpt-5.4-mini | 需要外网访问 |
| 本地 Ollama | http://localhost:11434/v1 |
支持所有 Ollama 模型（ollama/*） | 完全离线 |
任何兼容 OpenAI API 格式的服务商都可以接入，只需配置对应的 Base URL 和 API Key。
ZhikunCode 当前预置了 17 个阿里云百炼 MCP 服务、共 83 个白名单工具。运行时采用服务级最小化默认策略：智谱联网搜索、高德地图、千问图像和万相视频默认开启；新闻、法律、企业信息、文本审核、金融、学术、采购、物流、行情和行业洞察等 13 个低频或高风险服务默认关闭。没有配置百炼 Key 时会跳过远端连接，不影响核心对话、代码编辑和本地工具使用。
默认关闭或被用户关闭的 MCP 不建立连接、不注册工具，也不会向模型上下文注入工具描述；直接调用会被拒绝。点击页面顶部的 MCP 徽章可打开 MCP 管理，按服务即时启用或关闭，选择保存在本机且无需重启。
| MCP 服务 | 传输 | 能力 | 工具数 |
|---|---|---|---|
| 高德地图 | SSE | 地理编码、IP 定位、天气、搜索、距离与四类路线规划等 | 13 |
| 千问-图像生成（QwenImage） | HTTP | 文生图、单图编辑、多图融合 | 3 |
| 万相-视频生成（WanVideo） | HTTP | 文生视频、图生视频、数字人、首尾帧视频及结果查询 | 8 |
| OneKey 新闻查询 | HTTP | 频道、热榜、按频道或标题检索新闻 | 3 |
| OneKey 得理法律数据 | HTTP | 法规与类案检索 | 2 |
| OneKey 上奇企业工商 | HTTP | 企业匹配、工商、股东、人员、投资、分支、联系方式 | 7 |
| OneKey 文本内容审核 | HTTP | 违规、推广、辱骂、低质和广告法风险审核 | 1 |
zhipu-websearch |
SSE | 智谱联网搜索 Pro | 1 |
| 东方财富妙想 | HTTP | 股票行情、公告、研报、财务、资金与市场数据查询 | 11 |
| 企业知识产权 | HTTP | 企业知识产权信息查询 | 1 |
| 万方文献 | HTTP | 学术文献检索与详情查询 | 2 |
| arXiv 论文 | SSE | 论文搜索、详情、作者与分类查询 | 4 |
| 1688 选品 | HTTP | 商品选品与货源查询 | 1 |
| 物流快递 | SSE | 快递物流查询与轨迹跟踪 | 2 |
| 贵金属行情 | HTTP | 黄金、白银等贵金属行情与市场数据 | 6 |
| 连锁商业 / 茶饮洞察 | HTTP | 连锁品牌、门店、商圈与茶饮市场洞察 | 8 |
| 旅游洞察 | HTTP | 景区、客流、酒店与旅游市场数据分析 | 10 |
如需使用（需要阿里云百炼 API Key，并在控制台开通相应 MCP 能力；部分服务调用可能产生费用，具体以百炼控制台为准）：
- 在
.env中配置 DashScope Key：LLM_PROVIDER_DASHSCOPE_API_KEY=sk-xxxxxxxx
- 修改
.env后按原部署方式重启：Docker 用原 Compose 文件与 override 执行up -d应用配置；手动启动者重新加载.env后重启后端；使用启动脚本的用户才执行 stop／start（脚本会清理固定端口）。 - 在页面顶部打开 MCP 管理，仅启用当前任务需要的服务；后续开关即时生效，无需重启。
注册表中的
"enabled": true表示该工具进入管理员白名单，不等于服务在运行时默认开启。工具必须同时通过注册表白名单、服务开关和凭证可用性三层检查。
2026-05 历史运行使用 qwen3.7-max 和六个工具，无子 Agent；官方 harness 结果为 168 / 300（56.0%）Resolved，284 / 300 生成 Patch。公开产物见 历史归档。
至少一例公开轨迹包含对应的已合并修复，不能将成绩无条件视为未接触参考修复的独立完成率。 sympy__sympy-11897 第 37、39 次 Bash 输出包含参考修复，源码修改块与最终预测补丁相同；实际工具输入记录为 {}，不能据此判断来自实时联网还是已有材料，也不能推断其他实例无效。原说明指向的 swe-bench/swe_bench.py 未纳入 Git；仓库另有评测脚本，但它与历史材料的预算和版本条件不同，公开材料不足以严格重跑原环境。
| 指标 | 数值 | 出处 |
|---|---|---|
| Resolved Instances | 168 / 300 (56.0%) | docs/swe-bench/20260525/results.json resolved_instances=168 |
| Patch 生成率 | 284 / 300 (94.7%) | all_preds.jsonl（其中 16 条空 patch） |
| 历史主干模型（保留原记录） | qwen3.7-max |
docs/swe-bench/20260525/metadata.yaml |
| 工具闭集 | Read / Edit / Write / Bash / Grep / Glob | 历史提交说明与公开轨迹 |
| 单实例预算 | 历史材料口径不同 | 原主 README、归档说明和当前脚本不一致，不能用当前默认值反推历史条件 |
| 说明中的并发 worker | 1 | 历史说明，不作为当前部署默认值 |
| 网络 / Sub-agent | 无子 Agent；联网状态不能仅凭提示声明认定 | 已发现参考修复内容，详见上文 |
| 提交命名空间 | 20260525_zhikuncode |
metadata.yaml |
| Repository | Resolved / Total | Resolve Rate |
|---|---|---|
| mwaskom/seaborn | 3 / 4 | 75.0% |
| django/django | 82 / 114 | 71.9% |
| astropy/astropy | 4 / 6 | 66.7% |
| sympy/sympy | 42 / 77 | 54.5% |
| scikit-learn/scikit-learn | 12 / 23 | 52.2% |
| pytest-dev/pytest | 8 / 17 | 47.1% |
| pydata/xarray | 2 / 5 | 40.0% |
| matplotlib/matplotlib | 8 / 23 | 34.8% |
| psf/requests | 2 / 6 | 33.3% |
| sphinx-doc/sphinx | 4 / 16 | 25.0% |
| pylint-dev/pylint | 1 / 6 | 16.7% |
| pallets/flask | 0 / 3 | 0.0% |
| Total | 168 / 300 | 56.0% |
当前主干可查阅 ContextCascade 和 QueryEngine 的上下文管理、工具循环与恢复策略；这是当前实现说明，不能据此推断历史运行器启用了全部机制。自纠错（SelfCorrectionLoop） 为可选开关，默认关闭。
公开证据的范围与文件校验
黄金监控与 12306 案例保留评分 JSON、公开日志摘录和图片；黄金完整原始日志和产物 ZIP 未公开，12306 的 HTML 可直接打开，另一实现的公开源码不等于已部署演示。2026-08-09 的 MOBA 案例有第一方代码、截图与派生视频预览，不把预览称为原始录屏。
手机到 Android 案例提供完整原录屏、在线游戏、开发介绍页、APK，以及网页游戏和 Android 工程源码，文件哈希见折叠说明。
两份原 SHA-256 清单对应 cd9261c7（2026-07-28）；该历史版本的黄金 10/10、12306 21/21 文件匹配。当前 HTML 和共用案例 README 有后续导航／说明变更，不再逐字匹配原清单；已核对的评分 JSON、日志摘录、图片和 12306 产物保持匹配。不要把当前整包写成全部通过，也不要将哈希一致当成业务内容或评分正确的证明。
原始材料：黄金证据 · 12306 证据 · 黄金清单 · 12306 清单。
从仓库根检查当前文件：
cd docs/case-studies
shasum -a 256 -c zhikuncode-codex-gold-monitor-SHA256SUMS.txt
shasum -a 256 -c zhikuncode-codex-12306-SHA256SUMS.txt报告和共用 README 的已知差异会返回校验失败；不要重生成清单来掩盖这些差异。
产品能力和版本变化较快，本节以公开同题任务和明确条件作比较；单次作品与评分不等于产品总体排名。
| 同题任务 | 已公开的比较 | 解读范围 |
|---|---|---|
| 黄金监控 | ZhikunCode 68.3、Codex 68.4；14 个维度 | 接近；模型不同，报告保留各自缺陷 |
| 12306 概念可视化 | ZhikunCode 8.68、Codex 8.45；单 HTML 与 Next.js 工程 | 差距小于报告区分阈值；公开源码不等于都已部署 |
| 宇树办公任务链 | 五款工具、六任务、30 件终稿 | ZhikunCode 与千问两榜均处近分组；ZhikunCode 六件需修正后采用 |
| 八方代码审查 | 同一提交的八份报告，附复核与复算材料 | 对比具体有效发现、误报和漏检，不外推总体能力 |
报告入口见公开工程案例。
采用时应逐项核对部署条件，而不把授权检查、容器部署和操作系统沙箱视为同一能力：
| 评估项 | ZhikunCode 当前行为 |
|---|---|
| 自托管与数据 | Java／Web 工作台自托管，运行数据保存于 SQLite 和本地文件；模型及外部服务接收相应输入 |
| 执行控制 | 项目授权、工具网关、持久审批、运行取消；新会话默认完全访问 |
| 隔离 | worktree 隔离代码目录；可选 Docker 命令沙箱默认关闭且不覆盖全部路径 |
| 账号边界 | 需配置入口认证与网络控制；实例访问控制不等于多租户隔离 |
| 能力维度 | 可核查的实现与使用入口 |
|---|---|
| 长任务推进 | 上下文级联、分级恢复、多 Agent 分工和结果接续；见架构及Agent |
| 行为与交付检查 | 浏览器／HTTP 断言、实际工具输出、逐次修改、证据与产物记录；验证依赖须就绪并实际调用 |
| 浏览器操作 | 桌面与手机查看任务、补充要求、处理审批、检查结果；重连恢复记录，重启不续执行栈 |
| 扩展 | Markdown Skill、Java SPI 插件、MCP 服务和可配置模型；各入口有独立启用条件 |
ZhikunCode 采用三端分离架构，Java 后端负责核心编排，React 前端提供交互界面，Python 服务提供代码分析、浏览器自动化与 HTTP 验证能力：
┌──────────────────┐ WebSocket / HTTP ┌──────────────────────┐
│ Frontend │ ◄────────────────────────► │ Backend │
│ React 18 + TS │ │ Java 21 + Spring │
│ Vite + Tailwind │ │ Boot 3.4 │
│ :5173 (dev) │ │ :8080 │
└──────────────────┘ └──────────┬───────────┘
│ HTTP
▼
┌──────────────────────┐
│ Python Service │
│ FastAPI + Uvicorn │
│ :8000 │
└──────────────────────┘
| 层 | 技术栈 | 职责 |
|---|---|---|
| 后端 | Java 21, Spring Boot 3.4.x, WebSocket, SQLite | 核心编排引擎、LLM API 路由、Agent 管理、内置工具与 MCP 动态扩展、统一授权网关、会话持久化 |
| 前端 | React 18, TypeScript 5.6, Vite 5, TailwindCSS, Monaco Editor, xterm.js, Zustand | 对话式交互 UI、代码编辑器、内置终端、文件浏览器、设置面板、实时流式输出、委派结果查看 |
| Python 服务 | FastAPI, Uvicorn, Python 3.11/3.12 | 代码分析、AST 解析、浏览器自动化与 HTTP 验证，以及文件和 Git 等辅助 API |
生产环境通过 Docker 单容器部署。镜像包含 Java 后端、内置静态前端和 Python 运行时；基础 Compose 默认只启动 Java 进程，受管 Python 服务需通过显式的环境变量/override 启用：
┌─────────────────────────────────────────────────┐
│ Docker Container │
│ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ Backend │ │ Python* │ │ Frontend │ │
│ │ :8080 │ │ :8000 │ │ (静态文件) │ │
│ └───────────┘ └───────────┘ └──────────────┘ │
│ │
│ Volume: zhikun-data (SQLite + 会话数据) │
│ Volume: workspace (用户项目代码) │
├──────────────────────────────────────────────────┤
│ Port: 8080 → 宿主机 │
└──────────────────────────────────────────────────┘
* Python 服务为可选的容器内受管进程，不对外暴露端口，也不由基础 Compose 默认启动。
ZhikunCode 的智能决策由以下核心引擎协同驱动：
| 引擎 | 职责 | 关键特性 |
|---|---|---|
| 查询引擎（QueryEngine） | Agent 决策与工具执行编排 | 多步迭代循环，驱动完整 Agent Loop |
| 授权服务（AuthorizationService） | 统一策略与授权裁决 | 系统不变量、权限模式、Grant 匹配、持久交互 |
| 操作分析器（OperationAnalyzerRegistry） | 工具语义与风险分析 | 文件、Bash、网络、MCP/动态工具分类 |
| 工具授权网关（ToolExecutionGateway） | 工具执行唯一入口 | 执行槽、最终授权复检、结构化执行结果 |
| 权限 Grant 仓库（PermissionGrantRepository） | 授权保存、匹配和撤销 | RUN/SESSION/WORKSPACE 作用域与父子 Agent 继承 |
| 上下文级联（ContextCascade） | 上下文压缩与恢复 | 6层级联 + 413两级上下文压缩 |
| 图片注入器（ImageRefInjector） | 图片引用安全注入与预算管理 | 候选选取、动态预算、完整性校验和去重 |
| Token预算守卫（TokenBudgetGuard） | 两阶段 Token 预算控制 | 历史 Base64 预清理 + 最终 payload 梯度降级 |
| 工具执行管线（ToolExecutionPipeline） | 工具执行全生命周期 | 校验、输入冻结、授权、执行和结果归一化 |
| 自纠错循环（SelfCorrectionLoop） | 可选错误诊断与修复提示 | 默认关闭；配置启用后仍有尝试次数和运行预算限制 |
| RunControlService | Run 生命周期 CAS | 状态原子更新，COMPLETED/FAILED/CANCELLED/INTERRUPTED 单一终态权威 |
| RunExecutionRegistry | 活跃 Run 执行注册 | 以 Session 映射内存活跃 Run、输入队列与取消上下文；不承担 checkpoint 持久化 |
| DurableInteractionService | 持久交互 | Inbox、ACK、服务端 deadline、CAS 终态与重连恢复 |
| Project 工作空间服务 | Project 选择与信任边界 | 持久授权、真实路径规范化、Session 工作目录固定、符号链接/别名/重绑定及越界复检 |
| Artifact Manifest 与发布策略 | 产物归属、完整性与发布检查 | Manifest 登记文件并校验哈希；OSS 有普通工作区文件回退，秒悟强制绑定通过的运行验证证据与发布快照 |
| BestEffortObservabilityRecorder | 补充观测故障隔离 | 有界异步事件队列、丢弃/写失败指标；记录失败不反向破坏主执行链 |
| 日志关联与恢复投影 | 诊断关联和断线恢复 | MDC 提供 sid/rid/prid/agent/turn/tool/llm；完整 Session 快照、Run event sequence、活跃工具状态及持久交互重放恢复前端 |
ZhikunCode 的 QueryEngine 通过多步迭代循环驱动 Agent 决策与工具执行：
压缩级联（ContextCascade）→ 流式会话创建 → API 调用（含熔断、自适应重试和降级保护）→ 响应收集 → 工具结果消费（ToolExecutionPipeline）→ 终止评估 → 工具摘要注入 → 状态更新
关键子系统：
| 组件 | 职责 | 配置项 |
|---|---|---|
| IncrementalCollapseManager | 当前按代码常量每 10 轮尝试增量折叠 | 同名 YAML 数值未绑定，不能假定修改配置即可调整 |
| ContextCascade | 六层压缩级联（Snip→MicroCompact→ContextCollapse→AutoCompact→CollapseDrain→ReactiveCompact） | context.cascade.* |
| MicroCompactService | 清除旧工具结果内容，保护近期内容 | 主循环调用；CACHED_MICROCOMPACT 仅控制提示段 |
| ModelTierService | 模型降级与冷却；无 retryAfter 时默认 30 分钟，恢复还取决于后续成功调用 | app.model.tier-chain |
413 恢复：由 QueryEngine.java 编排，先尝试两级上下文压缩：
- Level 3 — CollapseDrain 激进压缩，按当前恢复预算收缩历史
- Level 4 — ReactiveCompact 反应式压缩，进一步缩减历史并保留必要上下文
若仍失败且错误与媒体相关，再尝试移除媒体块；恢复耗尽后释放错误并终止，不继续落入普通模型降级。两级压缩不等同于完整错误恢复链路。
收到上游明确的 token 上下文超限响应后，系统会按被拒请求的历史估算量，为本次执行中的实际模型收紧恢复预算；限制不带入下一次执行。恢复保留用户原文与完整工具事务；必要内容仍无法满足恢复目标时会停止恢复并提示新开会话。恢复实现 · 回归用例。
六层压缩级联（ContextCascade）详解
| 层级 | 名称 | 语义 | 触发条件 |
|---|---|---|---|
| L0 | Snip（首选裁剪） | 按模型窗口预算截断过长工具结果 | 每轮检查工具结果预算 |
| L1 | MicroCompact（微压缩） | 清除旧工具结果并保护近期内容 | 按保留尾部规则处理 |
| L1.5 | ContextCollapse（渐进折叠） | 渐进折叠历史；增量折叠另以代码固定的 10 轮 Agent 循环阈值判断是否触发 | 启用对应机制时 |
| L2 | AutoCompact（自动压缩） | 系统自动压缩全局上下文 | 常规阈值突破 |
| L3 | CollapseDrain（激进压缩） | 按恢复预算激进压缩 | 上游上下文拒绝后的第一阶段 |
| L4 | ReactiveCompact（反应式压缩） | 进一步缩减历史并保留必要上下文 | 第一阶段仍不足时 |
源码：ContextCascade.java
工具执行由授权、风险分析和具体执行路径共同约束。新会话默认完全访问（AUTO_APPROVE）；需人工确认时应先切换权限模式。授权控制、Git worktree 与 Docker 沙箱分别解决不同问题。
| 环节 | 当前行为与边界 |
|---|---|
| 命令与资源分析 | 解析命令、识别风险及资源，拒绝明确禁止的操作；不等于能识别所有 Shell 行为 |
| 工具授权 | 按权限模式、Grant 与交互裁决；完全访问可自动批准到达授权阶段的高风险操作 |
| 执行前检查 | 复核对应执行路径的目录、授权状态及运行准入；各工具分析器的复检范围不同 |
| 进程与输出 | 受管执行有超时、终止和输出限制；取消回执不等于所有进程已经退出 |
| Docker 命令沙箱 | 默认关闭；开启后还需 Docker 可用及执行路由支持，不覆盖所有后台／工具路径 |
| 记录与诊断 | 工具结果、运行事件与审计记录帮助追踪；记录存在不证明业务结果正确 |
核心工具通过统一管线与网关进行授权，具体检查按工具类型实现：
Schema/Tool 校验
→ 规范化输入冻结
→ Operation Analyzer
→ 系统安全不变量
→ Grant / 权限模式 / 用户交互裁决
→ 获取执行并发槽
→ 路径、符号链接、环境和授权状态最终复检
→ Tool Gateway 执行
→ 结构化 Effect / Result / 审计事件
- 工具使用已冻结的规范输入执行，授权后修改原始参数不会改变实际执行内容。
- 高风险操作只能选择 ONCE，不生成可复用 Grant。
- Bash 的 SAFE／GUARDED 操作可记住 RUN／SESSION 工具范围授权，后续仍核对工具语义、风险和约束；不是只匹配原命令字符串，不支持 WORKSPACE。
- 受约束的文件读取和编辑可以选择 SESSION/WORKSPACE。
- 未知 MCP 和动态工具默认只能 ONCE；只有专用 Analyzer 才能产生可复用授权。
network-v1和mcp-v1的 SAFE/GUARDED 操作可选择 RUN/SESSION：保存的 Grant 仅匹配同一工具，输入值可变化；不支持 WORKSPACE，HIGH 风险仍只能 ONCE。- Grant 不能覆盖保护路径、符号链接逃逸、敏感环境变量和执行前动态变化。
- 用户决策以 SQLite 中的 Interaction CAS 终态为唯一权威。
Web 新会话必须先选择一个已授权目录。远程和 Docker 部署的目录浏览只展示服务端配置允许的根目录及其子目录；启用本地 picker 的直连本机部署中，内置目录浏览器从默认 workspace 起始，可浏览本机服务进程可读的目录。macOS 和 Windows 还会在系统能力可用时显示原生文件夹选择按钮，系统对话框通常从桌面目录开始；Linux 继续使用内置目录浏览器。Docker 中宿主机的 WORKSPACE_PATH 对应容器内的 /app/workspace。浏览器不能把客户端本地路径直接当作远程服务端路径。
- Project 是一个全局、持久、可撤销的信任范围和默认相对路径根，并不是通用的操作系统文件沙箱；专用文件工具以 Session 的规范化工作目录解析相对路径，范围外路径另行授权并复检。
- DEFAULT 模式下，Project 内的普通文件操作免于重复确认；Project 外的普通请求进入常规授权流程，并可在策略允许时记住授权；敏感文件和高风险操作仍需逐次批准。
- 撤销 Project 会停止后续普通写入的持久自动授权。已有 Session 仍以原目录作为默认相对路径根；安全读取仍按 Session 策略执行，其他受控操作重新进入正常授权流程。
- Session、Query 和文件搜索使用
projectId或sessionId；客户端提交任意workingDirectory会被拒绝。 - 普通目录和 Git 子目录都可授权；只有所选目录本身就是 Git worktree 根目录时，才提供内置仓库上下文和 Git slash 命令。Bash 不是目录沙箱，但始终走独立的命令授权，不会因 Project 选择而自动获准。
- 后端的
ZHIKUN_LOCAL_PICKER_ENABLED安全默认值为false。使用./start.sh本地快速启动时，如果ZHIKUN_WORKSPACE_ALLOWED_ROOTS和该变量均无非空配置，脚本会为直连本机桌面场景启用 picker；显式设置false或配置 allowed roots 时不会被覆盖或隐式启用。远程、反向代理和生产部署应显式保持关闭并配置 allowed roots。 - Python 的
WORKSPACE_ROOT是相对路径的默认锚点。配置ZHIKUN_WORKSPACE_ALLOWED_ROOTS后，Python 路由同样严格限制在这些根目录内；只有未配置 allowed roots 且显式启用本机 picker 的 loopback 开发模式，才允许分析用户选择的其他绝对路径。
| 范围 | 生命周期 | 子 Agent 行为 |
|---|---|---|
| ONCE | 当前一次操作 | 不持久化 |
| RUN | 当前直接执行 Run | DIRECT_ONLY，不被兄弟或后代继承 |
| SESSION | 当前根会话 | 根 Agent 及其后代可在相同约束下复用 |
| WORKSPACE | 当前规范化工作区 | 根会话及后代可复用受约束的文件能力 |
ONCE 是不写入 Grant 仓库的一次性授权决策；RUN、SESSION、WORKSPACE 才是三种持久 Grant 范围。
子 Agent 使用 root session、root run 和 actor ancestry 构成的授权主体匹配父会话 Grant。继承只复用相同工具语义和约束，不能扩大路径、命令、风险等级或资源范围。
| 模式 | 实际行为 |
|---|---|
| DEFAULT | 已授权 Project 内的普通文件编辑自动允许；其他无可复用 Grant 的受控操作请求用户确认 |
| PLAN | 允许安全工作区读取及列入 SAFE_INTERNAL 的内部操作；拒绝其他受控 Effect |
| ACCEPT_EDITS | 自动允许工作区内非高风险文件编辑，其他受控操作仍需确认 |
| DONT_ASK | 不创建交互；安全读取、已有 Grant 和已授权 Project 内普通文件操作可执行，其他需要交互的操作直接拒绝 |
| AUTO_APPROVE | 自动批准到达人工授权阶段的工具操作，包括工作区外文件、公共互联网请求和秒悟发布；秒悟发布仍强制验证证据绑定、快照一致性与内容安全检查；硬拒绝、安全 Hook、SSRF 防护和部署沙箱仍然生效 |
新建 Web、REST 和合并会话默认使用完全访问（AUTO_APPROVE），创建接口显式传入其他合法权限模式时使用该模式。已有会话的 REST 查询沿用保存的权限；若显式传入的 permissionMode 与会话不同，三个查询接口（包括 SSE）在开始执行前返回 HTTP 409，错误码 PERMISSION_MODE_MISMATCH，请先在页面修改会话权限。页面收到保存确认后更新显示；修改影响后续工具授权，已经获准或执行中的操作不会被终止。
AUTO_APPROVE 会取消工具权限确认（包括秒悟发布）；远程部署使用时应确认运行账户、文件系统和网络边界符合预期。它不会赋予操作系统之外的新权限，也不会绕过系统安全与部署限制。
以下路径由保护规则重点处理；不同工具及读写操作的结果不同。敏感文件读取可能进入高风险授权，不能把名单理解为任何权限模式下都绝对不可读：
.git— Git 仓库数据.env— 环境变量和密钥.ssh— SSH 密钥.gnupg— GPG 密钥.aws— AWS 凭证
镜像默认 ALLOW_PRIVATE_NETWORK=true 会放行所有到达后端的来源，并非只允许私网免认证。对外部署需在入口配置认证、TLS、防火墙和端口绑定；实例访问控制不等于多用户／租户隔离。改变该值须通过 Compose environment／override 显式传入，仅写根 .env 不会覆盖未透传变量。设为 false 后仍需核对代理来源与认证行为，不能当成完整公网身份体系。
模型 API、MCP 和发布服务会接收请求中的相关数据；自托管运行环境不代表外部调用全部留在本机。源码：访问过滤器。
-
权限、Bash、路径、符号链接、WebSocket、并发和数据库 CAS 均有专项测试覆盖
-
包含命令注入、路径穿越、权限绕过等攻击场景
-
v9.3 深度防御新增：
- CWE-22 路径穿越：
CoordinatorService.getScratchpadDirsessionId 白名单（11 单测），即使上游 URI 拦截被绕过，白名单仍为最终落盘防线 - 跨用户访问隔离（P2-A）：
BrowserReplayController双层闸门 —— sessionId 格式校验返回 400 + principal 归属校验返回 403，MVP 匿名会话兼容
v9.3 安全防御摘录：
防御层级 位置 防护机制 单测数 P1-2 CoordinatorService.getScratchpadDirsessionId 白名单 ^[A-Za-z0-9_-]{1,128}$11 P2-A BrowserReplayControllersessionId 格式校验 (400) + principal 归属校验 (403) — - CWE-22 路径穿越：
-
上述场景均有专项测试覆盖；完整安全套件通过本地回归或专项工作流执行。
历史测试报告见 全链路测试报告（目录名保留 v9.3，报告正文为 v9.5、2026-06-05）。下列数量均为注明日期的快照；历史采样总数不是当前独立测试用例数，也不代表当前提交已经通过全部检查。
持续集成：
- GitHub Actions 自动化流水线：主 CI 执行后端与 Python 测试、前端测试和构建；Docker 镜像验证仅在
mainpush 时执行。查看流水线。 - 公开案例校验：CI 通过
node scripts/verify-king-case.mjs复算 MOBA 公开材料，依赖 Node.js 22 和 FFmpeg；校验文件与记录一致性，不替代对业务效果的判断。校验脚本。
前端专项验证快照（2026-10-04，历史记录）：
- Vitest 全量单元测试：127 个测试文件通过，1220 PASS / 16 skipped（1236 total）；包含通知替换、旧计时回调竞态、卸载重挂和语法色板对比度回归。
- 主题浏览器回归：1440px／390px 视口下共 16 个主题与浓度组合场景、8360 项颜色与隔离断言通过；覆盖正文、链接悬停、行内代码、表格、99／100 行代码与手动高亮、消息操作、Mermaid、图片和图文混合消息。
- 历史跳过项：当时星舰主题在两个视口下的图片浮层交互因
clip-path裁剪问题跳过；2026-10-06 已修复并恢复回归，当前不再跳过。 - 静态与构建验证：TypeScript、改动源码 ESLint、Vite 生产构建和差异检查通过；构建仍提示部分分包超过 1000 kB。
此快照仅记录前端验证，不代表重新执行了后端、Python 或全栈会话链路测试。主题脚本使用真实消息组件和完整样式，在独立 Chromium 上下文中阻断网络请求；不启动业务服务、不读取现有会话，也不使用系统剪贴板。
历史本地验证快照（2026-09-02）：
- 后端单元/集成测试：1258 tests / 0 failure / 0 error / 62 skipped
- Python pytest：107 PASS
- 前端 vitest：207 PASS / 16 skipped（223 total）
- 简洁工作台 Playwright E2E：7 / 7 PASS
- 静态与构建验证：TypeScript 与 Vite 生产构建通过
历史专项与 E2E 基线：
- 36 模块 REST/WS/LLM/Session 冒烟：45/45 PASS（42 REST + 1 WS STOMP + 1 LLM 真推理 + 1 Session 持久化）
- E2E 差异化链路：Task 7 可视化自动路由（
/visualizemermaid/json/text）· Task 8 浏览器语义快照 MVP（/snap）全链路 PASS - APOS Phase 1 E2E：62 用例（9 模块，含 28 原始功能 + 34 支撑链路）100% PASS，覆盖 Activity 基础 UI / 数据流转 / 三层展示 / Signal 标记 / Feature Flag / 后端 API / 响应式 / 持久化，含 4 Bug 修复回归
- APOS Phase 2 E2E：5 模块 50 用例（变更影响全景 / Pipeline 视图与 DAG / 异常检测与告警 / 移动端响应式 / Phase 2 集成功能）48 PASS / 2 SKIP，通过率 96%
- APOS 风险修复专项：11 用例 100% PASS（工具调用 / 批量操作 / 并发竞态 / API 降级）
- AI Coding 功能增强专项：6 大模块（SelfCorrectionLoop / 精确Tokenizer / Skill预算安全 / BashTool动态超时 / GitDiffTracker / SearchStrategyRouter）33 用例 + 238 单元测试 + 7 集成测试 + Feature Flag 双向验证，100% PASS
- 历史功能验证：报告按当时用例范围记录结果，不代表当前版本全部功能完整或无缺陷
测试框架详情（2026-09-02 历史记录）：
| 框架 | 层级 | 覆盖范围 | 数量 |
|---|---|---|---|
| JUnit 5 + Mockito | 后端单元/集成测试 | 上下文/授权网关/技能/插件/LLM/MCP/记忆/并发/SSE/持久化/工具/工作台投影等（覆盖范围摘录） | 1258 tests / 0 failure / 0 error / 62 skipped |
| Vitest | 前端单元测试 | Store 生命周期/跨 Tab 同步/流式渲染/权限交互/重连恢复/工作台与路由边界 | 207 PASS / 16 skipped |
| Playwright + 节点脚本 | 端到端 E2E | 简洁工作台 / 可视化 3 种 viewType / 浏览器快照 MVP / APOS Phase 1 全栈 / APOS Phase 2 全栈 | 简洁工作台 7/7 PASS；其他历史结果与跳过项见报告 |
| Pytest | Python 服务测试 | Token 估算/文件处理/浏览器自动化/语义快照/代码分析器/CLI | 107 PASS |
历史性能采样（2026-05-09，本地 macOS，490 次请求）：
单连接串行采样，14 个混合端点包括前端首页与 Python 健康接口；不含 LLM 推理耗时，也不是并发压测。
| 指标 | p50 | p95 | p99 |
|---|---|---|---|
| REST API（14 端点混合） | 1.5ms | 2.3ms | 4.3ms |
| WS STOMP 握手 | 2.22ms | 4.58ms | 6.22ms |
| 浏览器语义快照（热路径） | 9.23ms | 12.20ms | 12.26ms |
详细测试数据与证据：
- v9.3 完整报告：docs/test-results/v9.3/
- 分模块测试结果：docs/test-results/
- 前端 E2E 脚本：frontend/e2e/
- 隔离主题回归脚本：frontend/tests/browser/theme-regression.mjs
- E2E 截图证据：docs/test-results/screenshots/
从仓库根目录运行主题回归（首次运行先安装前端依赖与 Playwright Chromium；已安装时可直接执行测试命令）：
cd frontend
npm ci
npx playwright install chromium
npm run test:theme-regression该测试无需启动后端或前端开发服务器，失败截图写入系统临时目录。
📋 历史测试模块摘录（原报告共 36 个模块，保留原编号，点击展开）
| # | 模块 | 用例数 | 通过率 | 备注 |
|---|---|---|---|---|
| 1 | 环境准备与三端启动 | 7 | 100% | — |
| 2 | REST API 基础功能 | 33 | 100% | 逐端点验证 |
| 3 | WebSocket STOMP 通信 | 8 | 100% | — |
| 4 | Agent Loop 核心循环 | 9 | 100% | — |
| 5 | 工具系统与安全 | 10 | 100% | — |
| 6 | 权限治理与安全 | 6 | 100% | — |
| 7 | System Prompt 与 LLM | 7 | 100% | — |
| 8 | 记忆系统 | 7 | 86% | ★ 首次覆盖 |
| 9 | 技能系统 | 7 | 100% | ★ 首次覆盖 |
| 10 | 插件系统与 MCP | 11 | 100% | ★ 首次覆盖 |
| 12 | Python 服务 | 15 | 100% | 1 BUG 已修复 |
| 13 | 前端 E2E 与 UI | 7 | 86% | 1 PARTIAL |
| 14 | 文件历史与补充 API | 11 | 100% | ★ 首次覆盖 |
| 15 | CLI 命令行工具 aica | 11 | 91% | 2 BUG 已修复 |
| 16 | 可视化功能 E2E | 19 | 100% | ★ 首次覆盖 |
| 17 | F3 代码复杂度分析 | 6 | 100% | ★ v1.0 新增 |
| 18 | F33 变更影响链路分析 | 6 | 100% | ★ v1.0 新增 |
| 19 | F25 API 契约可视化 | 6 | 100% | ★ v1.0 新增 |
| 20 | F35 代码→图表自动生成 | 25 | 100% | ★ v1.0 新增 |
| 21 | F40 代码路径追踪可视化 | 25 | 100% | ★ v1.0 新增 |
| 22 | 单元测试体系（v9.3 扩展） | 84 | 100% | 原报告模块级用例数，与独立 JUnit 数量不是同一口径 |
| 23 | APOS 基础 UI | 4 | 100% | ★ 首次覆盖 |
| 24 | APOS 数据流转 | 4 | 100% | ★ 首次覆盖 |
| 25 | APOS 三层展示 | 4 | 100% | ★ 首次覆盖 |
| 26 | APOS Signal与筛选 | 2 | 100% | ★ 首次覆盖 |
| 27 | APOS Feature Flag | 2 | 100% | ★ 首次覆盖 |
| 28 | APOS 后端API验证 | 1 | 100% | ★ 首次覆盖 |
| 29 | APOS 响应式+健康 | 3 | 100% | ★ 首次覆盖 |
| 30 | APOS Activity持久化 | 8 | 100% | ★ 首次覆盖 + 4 Bug 修复 |
| 31 | APOS 变更影响全景 | 6 | 100% | ★ Phase 2 新增 |
| 32 | APOS Pipeline视图与DAG | 12 | 92% | ★ Phase 2 新增 |
| 33 | APOS 异常检测与告警 | 10 | 100% | ★ Phase 2 新增，2 SKIP |
| 34 | APOS 移动端响应式 | 9 | 89% | ★ Phase 2 新增 |
| 35 | APOS Phase 2集成功能 | 13 | 100% | ★ Phase 2 新增 |
| 36 | AI Coding 功能增强 | 33 | 100% | ★ v9.4 新增（6子模块 + 238单元 + Feature Flag验证） |
ZhikunCode 的skill技能系统（Skill System）是一个 Markdown 驱动的可扩展工作流引擎。每个技能就是一个 .md 文件，用 YAML frontmatter 定义元数据，用 Markdown 正文定义执行指令。
PC 和平板通过顶部 Skill 入口、手机通过 更多 → Skill 管理 打开管理页，可搜索技能、查看来源与正文，并分别开启或关闭。现有与新增技能默认开启。设置由同一后端的所有设备和会话共享，默认保存到 ~/.zhikun/skill-states.json；可通过 SKILL_STATE_PATH 指定位置，Docker 使用持久化目录中的 /app/data/skill-states.json。
开关按技能内部名称保存，同名覆盖、文件热加载或删除后重建同名技能都会保留原有选择。
保存后立即拦截新的技能调用，下一条用户消息使用更新后的配置，无需重启。关闭的技能不出现在可用列表或技能建议中，不再自动加入其描述、正文和对应 token 开销；全部关闭时移除 Skill 工具。页面可见时每 5 秒同步一次其他设备的设置，也可手动刷新。
如果技能设置文件损坏或无法读取，后端仍会启动，但所有 Skill 暂时关闭。管理页会显示错误并禁止保存，原文件不会被覆盖；修复提示中的配置文件后，重启后端恢复正常管理。
当前回答与已经开始的技能执行继续运行；旧聊天历史中的技能内容仍可能影响模型，新聊天可获得干净上下文。开关管理的是技能加载与调用，不会隔离磁盘文件。技能对应的独立命令、底层工具及部署配置仍有各自的启用规则，例如关闭 review Skill 不会关闭独立的 /review 命令。
在 Web 输入框输入 /skill <技能名> 打开技能弹窗，填写参数或任务说明后执行。内置 commit、pr、test、verify、debug、remember、software-architecture、prompt-engineering、csv-data-summarizer、test-driven-development 会在模板后保留完整补充说明；内置 review 将完整说明作为审查范围。Web /skill 与模型调用 Skill 都使用这套渲染规则。其他技能（包括项目或用户提供的同名覆盖）仍按声明参数替换模板，不自动追加原文。
发布使用表中的专用命令；同名直接命令（如 /review）有独立实现。内置 13 个工作流默认启用，实际调用仍受开关、工具权限与服务配置约束。部署未启用 OSS 或秒悟时，对应 /publish-oss 或 /publish-meoo 不出现在命令列表和补全中；启用部署功能后仍需对应 Skill 可用。
| 技能 | 命令 | 功能 |
|---|---|---|
| 智能提交 | /skill commit |
分析暂存区变更，按 Conventional Commits 格式生成 commit message |
| 代码审查 | /skill review |
审查未提交变更，按 P0/P1/P2/P3 严重程度分类问题 |
| 智能测试 | /skill test |
为指定代码或近期变更生成/运行测试，覆盖边界情况 |
| PR 助手 | /skill pr |
分析分支差异，生成结构化 PR 描述和审查说明 |
| 调试诊断 | /skill debug |
按需求进行根因诊断、最小修复或脱困分析 |
| 代码验证 | /skill verify |
按项目技术栈和改动风险选择构建、测试及静态检查 |
| 项目笔记 | /skill remember |
显式保存、检索和更新项目共享笔记；不保证新会话自动读取 |
| 架构分析 | /skill software-architecture |
Clean Architecture + SOLID + 设计模式评估 |
| 数据摘要 | /skill csv-data-summarizer |
CSV统计分析+可视化图表+Markdown报告 |
| Prompt工程 | /skill prompt-engineering |
优化prompt结构、清晰度和有效性 |
| 测试驱动开发 | /skill test-driven-development |
TDD红→绿→重构循环方法论指导 |
| OSS 产物发布 | /publish-oss |
显式发布工作区单文件；匹配 Manifest 时校验条目与哈希，无匹配时按文件策略检查。部署默认关闭，审批依当前权限模式 |
| 秒悟应用发布 | /publish-meoo |
每次创建新站点、保留旧站点并占用平台额度；结果卡显示匿名访问验证状态。配置与使用说明 |
当前启动时依次加载内置、项目和用户技能，同名定义由后加载者覆盖；这不是支持删除后自动回退的分层注册表：
bundled → project → user
| 来源 | 目录 | 说明 | 状态 |
|---|---|---|---|
| managed | 策略管理目录 | 企业统一下发的技能 | 预留 |
| user | ~/.zhikun/skills/ |
用户全局自定义技能 | ✅ 已实现 |
| project | .zhikun/skills/ |
项目级技能；是否纳入版本控制取决于 Git 忽略规则 | ✅ 已实现 |
| plugin | 插件提供 | JAR 插件内嵌的技能 | 预留 |
| bundled | 内置 | 13 个工作流定义，执行依赖各自条件 | ✅ 已实现 |
| mcp | MCP 构建 | 通过 MCP 协议注册的技能 | 预留 |
在后端运行用户的 ~/.zhikun/skills/translate.md 中保存以下示例，重启后端加载。project 来源的 .zhikun/skills/ 按后端启动目录解析，不随界面选择的 Project 切换：
---
description: "将代码翻译为指定语言"
arguments:
- language
---
# 翻译任务
将原对话中明确指定的代码翻译为 {{language}}，保持原有逻辑和必要注释。Web 调用方式：输入 /skill translate，在弹窗参数栏填写 language=python 或 python，再执行。
可解析的 frontmatter 字段：
模型调用 Skill 工具时，渲染正文通过工具结果返回；Web /skill 通过命令路径将渲染提示送入当前对话。
| 字段 | 类型 | 说明 |
|---|---|---|
description |
string | 技能描述 |
name |
string | 显示名称（覆盖文件名） |
arguments |
list | 参数定义列表 |
argument_hint |
string | 参数提示文本 |
when_to_use |
string | 使用条件描述元数据 |
allowed_tools |
list | 技能声明的工具列表；不能替代实际工具权限控制 |
context |
string | inline（默认）将渲染正文作为工具结果返回；fork 返回正文和执行元数据，当前入口不自动创建子代理 |
model |
string | 模型声明（inherit 表示不指定覆盖）；当前执行器返回此元数据，不自动切换模型 |
version |
string | 技能版本号 |
disable_model_invocation |
boolean | 模型调用偏好声明（默认 false）；当前工具入口未据此禁止模型调用 |
user_invocable |
boolean | 手动调用偏好声明（默认 true）；当前入口未据此限制调用 |
hooks |
object | 钩子配置（预留） |
effort |
string | 推理强度声明；fork 结果携带此元数据，当前不自动调整模型请求 |
agent |
string | 关联代理名称声明；fork 结果携带此元数据，当前不自动创建对应代理 |
paths |
list | 文件路径 glob 模式声明（元数据） |
shell |
string | Shell 类型声明（默认 bash）；当前不据此启动或切换 Shell |
已监听的项目技能目录支持热更新（500ms 防抖）；用户目录新增或修改后建议重启。删除同名覆盖文件不会自动恢复内置定义；修改内置资源或清理覆盖文件后，应重新构建并重启后端，再刷新前端菜单。
安全与运行控制：
- 技能加载与上下文：不设置单技能或会话累计的 token 加载额度；模型上下文容量、运行轮次和输出限制仍然适用，重复加载仍会增加实际输入 token 消耗。
- 工具声明：
allowed_tools描述预期工具；当前不保证运行时强制执行这份列表，实际工具权限仍然适用 - 文本技能检查：模型调用
Skill时，上述 10 个内置补充说明技能及内置review按原始说明全文检查 2000 长度上限（JavaString.length()，包含参数名、空白和换行），不将 Markdown 或代码示例按 shell 危险模式过滤。对这 10 个技能，全文限长比此前逐参数限长更严格：单个参数未超限也可能因全文超限而被拒绝。本次保留此工具入口限制。 - 其他技能检查：通过
Skill工具调用其他技能（包括自定义技能、同名覆盖和发布技能）时，仍对每个解析参数检查 2000 长度上限及六类危险正则模式：$(...)、反引号、; command、管道命令、&& rm、${...}。 - Web 命令入口：
/skill不经过SkillToolValidator，本次未给该入口新增上述长度或正则检查；同一段说明可能在 Web 命令入口可用、在Skill工具入口因全文超限被拒绝。后续实际工具调用仍经过授权和执行检查。 - Fork 深度检查：fork 模式检查调用时的当前上下文深度，深度 ≥3 时拒绝；该入口仍只返回渲染正文与元数据。
ZhikunCode 的插件系统通过标准 Java SPI（ServiceLoader） 机制发现和加载第三方 JAR 插件，提供四大桥接能力：命令注册、工具注册、钩子拦截、MCP 服务器集成。plugin.enabled（默认 true）控制启动时自动加载，不是所有入口的运行时禁用开关；显式 reload／install 入口仍可初始化插件。
| 桥接类型 | 说明 | 示例 |
|---|---|---|
| 命令注册 | 插件可注册自定义斜杠命令，自动添加插件前缀 | /myplugin:hello |
| 工具注册 | 插件可提供自定义工具供 AI Agent 调用 | 自定义代码分析工具 |
| 钩子拦截 | 插件可在关键事件前后执行自定义逻辑 | 工具执行前安全审计 |
| MCP 服务器 | 插件可注册 MCP 服务器扩展 AI 能力 | 连接外部数据源 |
- PluginClassLoader 类加载控制 — 插件通过包白名单访问宿主 API：核心 API 包（
com.aicodeassistant.plugin.*、tool.*、command.*、mcp.*）、标准库（java.*、javax.*、jdk.*、sun.*、org.slf4j.*）、基础框架（org.springframework.*、com.fasterxml.jackson.*、jakarta.*）。未在白名单中的宿主类访问会抛出ClassNotFoundException。插件仍在后端进程执行，这不是针对恶意代码的操作系统沙箱 - 钩子执行超时保护 — 设置 5 秒等待超时；前置安全钩子失败或超时会拒绝执行，其他展示类钩子失败记录后继续。等待超时不等于插件线程已停止
- JAR 文件验证 — 加载前校验文件存在性、JAR 格式合法性、大小限制（默认 50MB）、SPI 配置文件（
META-INF/services/）完整性 - API 版本兼容检查 — 插件声明
minApiVersion/maxApiVersion，宿主自动校验兼容性
支持运行时重新加载所有插件，无需重启服务：
- 使用
ReentrantReadWriteLock串行化重载与相关查询；不代表所有执行中的插件任务都已停止 - 重载流程：卸载所有插件（注销命令/工具/钩子/MCP + 关闭 ClassLoader）→ 重新扫描加载
- 触发方式：
/reload-plugins斜杠命令 或 REST API
插件接口声明以下事件；实际触发以接入链路为准，TaskCompleted 当前没有自动触发调用方：
| 事件类型 | 触发时机 |
|---|---|
PreToolExecution |
工具执行前 |
PostToolExecution |
工具执行后 |
UserPromptSubmit |
提示词提交时 |
SessionStart |
会话开始 |
SessionEnd |
会话结束 |
TaskCompleted |
声明已存在，尚未自动触发 |
Notification |
通知事件 |
Stop |
停止事件 |
开发一个 ZhikunCode 插件只需四步：
1. 实现 PluginExtension SPI 接口
public class MyPlugin implements PluginExtension {
@Override public String name() { return "my-plugin"; }
@Override public String version() { return "1.0.0"; }
@Override
public List<Command> getCommands() {
return List.of(/* 自定义命令 */);
}
@Override
public void onLoad(PluginContext ctx) {
ctx.getLogger().info("Plugin loaded!");
}
}2. 在 META-INF/services/ 中注册 SPI
# META-INF/services/com.aicodeassistant.plugin.PluginExtension
com.example.MyPlugin
3. 将 JAR 放入 ~/.zhikun/plugins/ 目录
4. 重启服务或执行 /reload-plugins 热重载
PluginExtension接口采用默认方法设计 — 最小实现仅需name()和version()，其余能力（命令/工具/钩子/MCP）按需覆写。
ZhikunCode 提供个人记忆与项目约定管理，也有团队 Markdown 组织方式；不同来源的加载入口不同。可把常用构建、测试和工程约定保存下来，在后续任务中复用。
| 层级 | 文件 | 作用域 | 说明 |
|---|---|---|---|
| 个人记忆 | ~/.ai-code-assistant/MEMORY.md |
全局跨项目 | 通过 Memory 工具或页面读写，主会话请求自动限量加载 |
| 项目记忆 | zhikun.md / zhikun.local.md |
当前项目 | 项目级编码约定、架构决策、构建流程 |
| 团队记忆 | .zhikun/team-memories/*.md |
团队共享 | 随代码库分发，经普通文件读取按需使用；未自动注入普通会话 |
实现支持四类标签；普通 Memory 工具写入默认使用 semantic，不能理解为自动语义分类：
| 分类 | 说明 | 示例 |
|---|---|---|
| 语义记忆（semantic） | 项目知识、用户偏好、技术约定 | 「这个项目使用 JUnit 5 + AssertJ」 |
| 事件记忆（episodic） | 具体操作历史、调试经过 | 「上次部署时端口冲突的解决方法」 |
| 程序记忆（procedural） | 常用工作流、部署流程 | 「每次提交前先跑 mvn test」 |
| 团队记忆（team） | 团队级共享知识和规范 | 「API 返回统一使用 Result 包装」 |
- 主会话自动加载 — 普通主会话与 Coordinator 主模式每次请求重新读取个人
MEMORY.md，并加载所选 Project 根的zhikun.md与zhikun.local.md，不向父目录搜索。页面保存成功后，下一次请求生效；同一次请求内的工具循环不会中途刷新。 - 范围与优先级 — Override 完全替换系统提示时跳过记忆注入和 append；custom system prompt 实际被选为基础提示时，也不自动注入记忆，但保留 append。仅提供 custom 字段而由更高优先级的 Coordinator／Agent 分支胜出时，仍按该分支加载记忆。子代理尚未统一接入这条加载链路。记忆冲突时，
zhikun.local.md > zhikun.md > MEMORY.md，记忆不凌驾于用户当前的明确指令。 - 个人记忆工具 — Memory 提供 read／write／delete；实际是否写入取决于调用，不保证每轮自动记忆。
- 团队资料 — 可用普通文件读取工具按需查看团队 Markdown；没有全量自动注入保证。
- 来源记录 — 条目支持 source 等元数据。
- 检索实现的状态 — 代码包含 BM25 与可选 LLM 重排，但尚未接入普通 Memory 工具或会话自动加载。不能把内部方法当作已经开放的搜索入口。
实现：记忆提示组装 · MemdirService · 项目约定加载。
点击页面顶部的 记忆 徽章，即可在页面中查看和编辑个人记忆（MEMORY.md）：
- 卡片模式 — 逐条查看、编辑、删除记忆条目，支持手动新增
- 整篇模式 — 以 Markdown 编辑器整体修改，支持实时预览
- 安全保护 — 保存时自动规范化条目格式、生成
.bak备份，并在内容被并发修改时进行冲突检测；PC / 平板 / 手机响应式布局
使用文件 API 时，先 GET /api/memory/file，将返回的 updatedAt 作为该份原稿的基线；提交 PUT /api/memory/file 或 PUT /api/memory/file/entries 时，通过 baseUpdatedAt 原样带回。不要给旧草稿换上后来刷新获得的新基线。省略 baseUpdatedAt、传 null 或空白字符串，均表示“加载原稿时文件不存在”，不是“文件存在但内容为空”；已有空文件也应使用 GET 返回的时间。基线与当前文件状态不一致时返回 HTTP 409；保留草稿、重新加载并核对合并后再保存，不自动强制覆盖。
在所选 Project 根目录创建以下文件，其内容会进入系统提示；是否准确执行仍需检查实际输出，不要在其中写凭证：
# zhikun.md — 项目约定（随代码库提交）
## 编码规范
- Java 方法命名使用 camelCase
- 测试类以 Test 结尾
## 构建流程
- 提交前必须跑 `./mvnw test`
- Commit 采用 Conventional Commits 格式# zhikun.local.md — 本地配置（不提交，加入 .gitignore）
## 本地环境
- 我的 API Key 在 .env 文件中
- 本地数据库端口: 5432项目记忆仅从所选 Project 根目录加载
zhikun.md和zhikun.local.md，不向父目录搜索；每个文件注入提示的正文最多保留 100 KiB（102,400 字节），超出时追加截断标记。zhikun.md随代码库提交用于团队共享，zhikun.local.md用于个人本地配置。
- 页面保存有 50,000 字符限制，并提供备份、并发冲突检测和原子替换。
- Memory 追加后的全文（含条目元数据）超过 50,000 字符时返回
MEMORY_FULL，原文件保持不变，不会自动删旧记忆腾空间。先用 Memory 的read查看，再以delete删除明确匹配的旧条目（content是删除匹配文本），或在页面整理、缩短后保存，即可重新追加；删除前确认匹配范围，避免误删同样包含该文本的其他条目。 - 项目约定有单文件读取上限与路径／符号链接检查。
- 个人记忆自动注入先取文件前 200 行（含元数据与空行），再限制为 25,000 字节（含截断标记）；页面可保存的全文不保证全部进入系统提示，截断不修改原文件。
- 独立团队记忆目录未接入上述自动加载链路；过期清理也没有周期调用。
除了 Web UI，ZhikunCode 提供复用后端引擎的命令行客户端，支持脚本输入、结构化输出和会话续接。
aica 是 ZhikunCode 的命令行客户端，设计为 UNIX 管道一等公民：
# 安装：先完成本地 Python 环境准备，从仓库根执行
python-service/.venv/bin/python -m pip install -e './python-service[cli]'
export PATH="$PWD/python-service/.venv/bin:$PATH"
# 基础使用
aica "帮我重构这个函数"
# 显式授权当前目录（仅 localhost 后端）
aica --working-dir "$PWD" "帮我重构这个函数"
# 远程后端使用已有 Project
aica --server https://example.com --project-id PROJECT_ID "检查项目"
# 管道输入 — 像 grep/sed 一样组合
cat src/main.py | aica "review this code"
# 结构化输出 + jq 处理
aica -f json "list all API endpoints" | jq '.result'
# 流式输出
aica -f stream-json "refactor this module"
# 继续上次对话
aica --continue "fix the bug we just discussed"未提供 --working-dir、--project-id，且没有通过 --session-id、--continue 或 --resume 选择 Session 时，CLI 使用后端默认 workspace。--working-dir 只适用于 localhost，远程后端应使用 --project-id；两者不能同时使用。
核心特性：
| 特性 | 说明 |
|---|---|
| 三种输出格式 | text（终端 Markdown 渲染）/ json（结构化）/ stream-json（SSE 流式） |
| 管道支持 | 自动读取 stdin，与 shell 管道无缝组合 |
| 权限模式 | --permission-mode default/plan/accept_edits/dont_ask/auto_approve 控制授权策略（CLI 未指定时新建默认完全访问、续接沿用会话权限；auto_approve 取消人工确认，含秒悟发布；不能绕过硬拒绝、安全 Hook、SSRF 或部署沙箱） |
| 会话管理 | --continue 继续上次会话，--resume <id> 恢复指定会话 |
| 模型选择 | --model 指定已配置模型；--effort 虽在 CLI 中解析，当前查询接口没有对应字段，不作为已生效功能 |
| 工具控制 | --allowed-tools / --disallowed-tools 白名单/黑名单 |
| 退出码 | 0=成功，1=通用错误，2=参数错误，3=连接错误，4=认证错误，130=Ctrl+C 中断 |
aica通过 HTTP/SSE 连接后端，共享模型与权限控制。--effort、--fallback-model、--fork-session、--json-schema虽能解析并发送，后端查询接口没有对应字段，不能依赖它们改变执行行为；以 CLI 与 查询接口 为准。自动化中应检查退出码和实际工具结果。
以下斜杠命令在 Web UI 中使用，
aicaCLI 通过自然语言 prompt 访问后端 Agent 引擎实现相同能力。
在 Web UI 中输入 / 或按 Ctrl+K 打开命令面板，支持模糊搜索和键盘导航：
| 类别 | 命令 | 说明 |
|---|---|---|
| 核心 | /help /clear /exit |
帮助、清除对话、退出 |
| 模型 | /model |
查看可用模型；切换请使用输入栏的模型选择器 |
| 诊断 | /doctor |
9 项系统诊断（Java/LLM/Git/JVM/Python/磁盘） |
| 压缩 | /compact |
手动触发上下文压缩，可附带指令（如 /compact focus on API） |
| Git | /diff /commit /review |
代码差异（/diff [unstaged|staged|--staged]；--cached 不再被接受，请用 staged）、暂存预览/直接提交、代码审查 |
| 配置 | /config /permissions |
查看配置、权限模式管理 |
| 会话 | /session /resume |
会话信息、恢复历史会话 |
| 成本 | /cost /usage |
Token 用量、费用统计 |
| MCP | /mcp-servers /mcp-tools |
MCP 服务管理 |
| 深度分析 | /ultrareview |
AI 深度审查（架构+安全+性能+并发） |
| 浏览器 | /snap |
语义快照 —— 捕获当前页面 DOM 结构与交互元素，生成 JSON 格式快照 |
| 可视化 | /visualize mermaid|json|text |
自动路由推送 —— 流式渲染 Mermaid 图表、JSON 数据或纯文本可视化结果 |
命令输入错误时，系统会基于 Levenshtein 距离自动建议相似命令。
ZhikunCode 是独立的 Web 应用。完成部署与访问控制后，可通过电脑、平板或手机浏览器跟进服务器上的任务。
参看手机操作 ECS 上的 ZhikunCode 交付游戏的实录：在线试玩、开发介绍页、APK 下载，以及同一部手机上的安装和游戏操作。
| 场景 | 使用方式与条件 |
|---|---|
| 离开电脑后跟进任务 | 手机浏览器查看运行状态、补充要求及处理待办审批 |
| 在另一台设备继续查看 | 连接同一后端恢复会话与运行事件；后端重启不自动续跑执行栈 |
| 在服务器处理项目 | 授权服务端目录；本地文件引用和远程上传是不同路径 |
| 团队评估部署 | 可共用受控实例，但需要自行明确访问身份、项目权限与数据边界 |
浏览器提供以下任务操作入口：
- 对话式编程 — 输入自然语言需求，Agent 自动生成代码，实时流式输出
- 权限审批 — 需要交互裁决时处理服务端提供的选项；默认完全访问可自动批准，并非每个敏感操作都弹窗
- 方案协商 — Agent 提出方案后可以在浏览器中讨论、修改、确认
- 任务管控 — 查看任务状态与结果，按任务 ID 请求取消并查询停止确认
- 文件浏览 — 在浏览器中直接查看和导航项目文件树
- 委派结果查看 — 通过对话中的工具结果查看子任务结果
前后端通过 STOMP over SockJS 保持实时连接（自动协商 WebSocket → xhr-streaming → xhr-polling 降级）：
- 流式输出 — LLM 响应逐字输出，无需等待完成
- 持久权限交互 — 权限请求先写入 SQLite，再投递到浏览器；刷新或断线重连后可恢复未完成请求
- 服务端终态裁决 — 浏览器只提交服务端下发的选项，允许、拒绝、过期和取消通过数据库 CAS 互斥裁决
- 服务端倒计时 — 权限决策窗口为 300 秒，前端只展示服务端 deadline，不在本地自动伪造拒绝
- 子 Agent 授权复用 — 后代 Agent 在严格约束下复用根会话 SESSION/WORKSPACE Grant，避免重复弹窗
- 状态同步 — Agent 工作状态变化即时反映在 UI 上
- 心跳保活 — 双向 10s 心跳检测，断线自动重连（指数退避 1s→10s）
- 消息保障 — 128KB 消息大小限制，1MB 发送缓冲，30s 发送超时
源码中保留以下 Bridge 组件，但连接与移动证据审批仍有未接通链路，不能作为完整跨端桥接功能宣传。普通浏览器远程操作不依赖它们：
| 组件 | 职责 |
|---|---|
| BridgeServer | 桥接服务端，管理设备连接和消息路由 |
| BridgeApiClient | 客户端 API 封装，支持远程调用 |
| TrustedDeviceManager | 可信设备管理，设备注册与认证 |
把独立调查、实现或验证交给子 Agent，让主 Agent 保持对整体目标的掌握；把需要持续查询的执行交给后台 Task，用任务 ID 跟踪状态与结果。两者都能让耗时工作与主对话配合推进，各自承担明确的职责。
Agent 工具通过 subagent_type 选择角色，SubAgentExecutor 为每次调用创建独立子会话与上下文，由角色提示和当前可用工具共同约束执行：
| 角色 | 适合的任务 | 工具范围 |
|---|---|---|
| 探索（explore） | 搜索代码、梳理调用链、定位实现与风险 | 当前启用工具中排除直接编辑工具与角色禁用项 |
| 验证（verification） | 复现问题、执行测试、寻找反例并给出证据 | 当前启用工具中排除直接编辑工具与角色禁用项；遵守验证角色的文件保护约束 |
| 规划（plan） | 分析需求、比较方案、拆解实施步骤 | 当前启用工具中排除直接编辑工具与角色禁用项 |
| 通用（general-purpose） | 实现功能、修复问题、完成完整子任务 | 当前启用工具，受公共禁用项与授权约束 |
| 引导（guide） | 查阅文档、解释配置与用法 | 仅 Glob、Grep、Read、WebFetch、WebSearch |
工具池从当前启用的内置工具、插件和 MCP 工具组装，再应用公共禁用项及角色 allow/deny 规则。子 Agent 不提供 Agent、TaskCreate、VerifyPlanExecution 等嵌套委派或验证编排入口。探索、验证和规划角色排除 Edit、Write、NotebookEdit 等直接编辑工具；仍可用的 Shell、浏览器或 MCP 操作继续受授权约束，工具过滤本身不是完整只读沙箱。
验证以证据为准。 verification 的角色提示要求保护源码、现有测试、配置、依赖与锁文件，在授权范围内执行测试并允许生成可复现的验证产物、缓存和临时脚本；不得为验证而安装依赖或进行 Git 写入。动态验证结论须引用实际命令和工具输出，静态分析须明确标注。报告需针对主要风险进行反例检查，并区分 PASS（验收范围已验证且无重大缺口）、FAIL（已确认失败）与 PARTIAL（尚未确认失败，但关键验证未完成）。这些是角色执行与报告规范，最终应结合实际证据审阅结论。
每次委派都需要在 prompt 中交代目标、已知结论、文件路径、授权边界与预期交付；子 Agent 从独立上下文开始。多个相互独立的 Agent 调用可在同一轮通过 Virtual Thread 并行执行，适合分别调查不同模块，或并行完成互不冲突的子任务。共享目录中的文件修改仍需避免重叠；上下文独立不等于文件隔离。
| 入口 | 调用与结果链路 | 适合场景 |
|---|---|---|
| Agent（同步） | 子会话执行 → 返回状态与结果 → 主 Agent 继续 | 下一步依赖该子任务结论 |
| Agent（后台） | run_in_background=true → 返回代理 ID 与输出文件路径 → 后台执行 → 当前 Run 收集结果 → 主 Agent 汇总 |
主 Agent 还有其他独立工作可推进 |
| TaskCreate | 提交后台执行 → 返回任务 ID → TaskList／TaskGet 查询状态与输出 | 需要单独查询、更新输出或请求取消的执行 |
| TodoWrite | 更新计划与进度清单 | 记录步骤与完成情况，不启动执行 |
后台 Agent 由 BackgroundAgentTracker 按父会话和父 Run 登记，WebSocket 推送启动、完成和失败事件。默认启用 BACKGROUND_AGENT_WAIT：主 Run 准备结束时，QueryEngine 等待当前 Run 尚未交付的后台 Agent 结果，将其作为任务数据回填上下文，再由主 Agent 生成汇总。结果不会成为新的授权或执行指令。
常规执行会对超过 100,000 字符的答案正文截断并附标记；Worktree 路径对包含交付、恢复信息的合成内容作同样处理。异常恢复及附加信息另有处理，因此这不是所有最终响应的统一硬上限。后台输出文件保存处理后的结果，父 Run 自动回填每个文件的前 4,000 字符，超长时附截断标记，并保留文件路径；可按路径读取更多已保存内容，文件本身也可能已被截断。
子 Agent 执行等待的基础预算默认 30 分钟，默认配置上限也为 30 分钟；执行等待超时后默认再等待 30 秒供退出。子会话初始化与 Worktree 准备、交付不计入这段执行等待计时，因此它不是调用总耗时上限。
父 Run 每批后台结果等待另设默认 31 分钟预算，与子执行等待分别计时；新一批等待独立获得预算，同一批唤醒不会刷新截止时间。可通过 FEATURE_BACKGROUND_AGENT_WAIT=false 关闭等待，或用 AGENT_TIMEOUT_MAX_WAIT_MINUTES 调整预算；提高子代理超时上限时应同步调整。等待超时会明确报告 BACKGROUND_AGENT_WAIT_TIMEOUT；取消、等待中断或主 Run 轮次耗尽也可能使结果收集未完成。此结果回收链路属于后台 Agent；TaskCreate 的执行结果通过任务工具查询。
子 Agent 的模型解析顺序为 显式 model 参数 → 父查询模型 → premium 别名，五种角色遵循同一规则。model 可选择可用的实际模型名或 light、standard、premium 别名；别名在 application.yml 的 agent.model-aliases 中配置，当前三者默认均为 qwen3.8-max-0902。
子 Agent 使用关联的根会话、根 Run 与代理祖先链进行权限裁决。符合工具语义和约束的 SESSION／WORKSPACE Grant 可按规则复用；继承不会扩大路径、命令、风险或资源范围。需要人工授权的操作通过根会话的持久交互流程处理。
执行结果区分 completed、failed、timeout、interrupted 和 max_turns，后台结果保留实际结束原因。执行等待超时会发出中止信号并等待退出窗口，能够恢复时附带部分进展；执行等待超时或取消请求本身不等于所有受管执行已经停止，应结合停止确认与恢复信息判断后续处理。
AgentConcurrencyController 提供全局 30 个、每会话 10 个并发准入名额，并设 3 层执行深度上限。超限请求会被拒绝；名额按执行路径释放，名额释放不构成底层执行已停止的确认。
Agent 的 isolation 提供两种选择：
| 隔离方式 | 行为 | 适合场景 |
|---|---|---|
| none（默认） | 使用父工作目录，子会话上下文独立 | 代码调查、验证、文件范围清晰的子任务 |
| worktree | 从项目已提交 HEAD 创建独立 Git Worktree，通过安全检查后自动合回 | 需要隔离文件修改的实现或实验 |
WORKTREE 不包含父工作区未提交的修改，也不会自动 stash 或提交父目录；实际执行目录与提示一致，原 Project 授权边界不扩大。授权根必须是有效仓库根；其内部子目录可映射到新树执行，无初始提交或 detached HEAD 不支持自动交付。
只有执行正常完成、受管工作已停止且目标分支、历史与工作区状态通过核验时才自动合回。已交付但清理失败仍为完成并附警告；未交付、冲突、超时或停止未确认会保留工作区与分支，并返回实际恢复位置。Git 自然退出后不会为清理终止 hook 后台进程。Linux 和 macOS 对仍在受管进程组内的普通后台后代保留目录；主动脱离该组的守护进程不在此保证内。其他平台沿用原有尽力跟踪能力，不承诺同等级的后代停止证明。停止服务也不删除 worktree 或代理分支。 自动交付遵守 Git 忽略规则：ignored 文件不会强制加入提交，正常清理时可能随目录删除；需要保留的交付文件应放在非忽略路径。子模块内部未提交内容会阻止交付，不递归提交。
Worktree remove 仅安全清理本进程登记、属于当前项目且已无占用的空树或已交付工作区，不提供强制丢弃。保留目录不是永久归档，也不承诺跨重启自动恢复管理。手动清理还会保守检查创建会话与当前会话的受管后台任务；同会话中无关的后台任务也可能使清理暂缓。内部串行化不覆盖外部 Git 或其他工具的并发写入。
TaskCreate 立即提交实际后台执行，返回任务 ID 和创建回执；任务是否成功由执行结果决定。支持 agent、shell，以及单次通用子代理兼容类型 local_workflow、monitor_mcp、dream；后三者不提供周期监控或特殊优先级。
任务通常经历 PENDING → RUNNING → COMPLETED / FAILED / CANCELLED；开始前取消可直接进入 CANCELLED。运行中的取消先登记请求，待执行与所属受管资源退出后发布终态。单任务默认 30 分钟超时，超时退出记为 FAILED 并保留超时原因。Task 在服务进程内共享 10 个并发名额，满额立即返回 TASK_CAPACITY_REACHED，不会排队等待空位；这一限额独立于 Agent 并发限制。
| 工具 | 职责 | 结果与边界 |
|---|---|---|
| TaskCreate | 创建并启动后台任务 | 用返回的 taskId 跟踪；创建成功不代表执行成功 |
| TaskList | 列出当前会话的任务 | 查看状态与输出摘要，可按状态筛选 |
| TaskGet | 查询当前会话内指定任务 | 获取状态、已保存的输出和可用错误信息，以及取消请求和停止确认字段；返回内容受长度限制 |
| TaskUpdate | 替换任务的存储输出 | 不改变执行状态；运行中的临时说明可被最终执行输出替换 |
| TaskStop | 按 taskId 请求取消当前会话的任务 |
回执表示请求已发出，继续用 TaskGet 确认退出 |
| TodoWrite | 维护计划与进度清单 | 记录待办与完成情况，不启动后台执行 |
Task 的执行状态由 TaskCoordinator 管理，查询区分“已请求取消”（cancellationRequested）与“停止已确认”（terminationConfirmed）。任务记录保存在服务进程内存中；输出与错误的存储、查询返回各有长度限制，超过时可能截断。TaskUpdate 可在任务结束后修订输出，但不会改写状态或错误；TaskStop 使用 Task 记录的任务 ID，后台 Agent 回执中的代理 ID 属于另一条执行链路。
典型用法：并行探索后，由主 Agent 汇总并决定自行实现或委派，再通过验证证据完成交付。
并行探索：多个 explore Agent 分别调查
-> 主 Agent 汇总结论与实施方案
-> 实现（主 Agent 完成或委派）
-> verification Agent 执行验证
-> 提交命令、输出与验证结论
-> 主 Agent 审阅证据并交付
需要单独跟踪长命令或后台代理任务时，用 TaskCreate 启动、TaskList／TaskGet 查询，必要时用 TaskStop 请求取消。计划拆解与进度展示使用 TodoWrite。
ZhikunCode 的 MCP（Model Context Protocol） 客户端支持 STDIO、SSE、HTTP 和 WebSocket，用于接入外部服务；另有可选 HTTP JSON-RPC 服务端入口，两者覆盖范围不同。
当前注册表收录 17 个预置服务、83 个白名单工具，不代表全部已连接或逐项实测。运行时还需通过服务开关、凭证、端点、账号开通／额度及远端工具列表检查，以管理页状态和实际调用为准。
- 默认开启（4 个）：智谱联网搜索、高德地图、千问图像、万相视频。
- 默认关闭（13 个）：新闻、法律、企业信息、文本内容审核、A 股金融数据、企业知识产权、万方文献、arXiv、1688 选品、物流、贵金属、零售洞察、旅游消费。
- 上下文隔离：关闭的服务不连接、不注册、不注入模型工具上下文，直接调用返回拒绝结果。
- 用户控制：点击页面顶部的 MCP 徽章进入 MCP 管理。开关即时生效，状态默认保存在
~/.zhikun/mcp-service-states.json；Docker 使用持久化路径/app/data/mcp-service-states.json。
| 工具 | 说明 | 来源 |
|---|---|---|
| 高德地图（13 项） | IP 定位、天气、地理编码、地点搜索、距离与路线规划 | DashScope MCP |
| 千问图像生成（3 项） | 文生图、单图编辑和多图融合 | DashScope Streamable HTTP MCP |
| 万相视频生成（8 项） | 文生视频、图生视频、数字人和首尾帧视频的异步提交与查询 | DashScope Streamable HTTP MCP |
| 网络搜索 Pro | 联网搜索，返回网页摘要 | DashScope MCP |
| OneKey 新闻 / 法律 / 企业 / 内容审核（13 项） | 外部数据查询与文本安全 | DashScope Streamable HTTP MCP |
| 东方财富妙想（11 项） | 股票行情、公告、研报、财务、资金与市场数据查询 | DashScope Streamable HTTP MCP |
| 企业知识产权（1 项） | 企业知识产权信息查询 | DashScope Streamable HTTP MCP |
| 万方文献（2 项） | 学术文献检索与详情查询 | DashScope Streamable HTTP MCP |
| arXiv 论文（4 项） | 论文搜索、详情、作者与分类查询 | DashScope SSE MCP |
| 1688 选品（1 项） | 商品选品与货源查询 | DashScope Streamable HTTP MCP |
| 物流快递（2 项） | 快递物流查询与轨迹跟踪 | DashScope SSE MCP |
| 贵金属行情（6 项） | 黄金、白银等贵金属行情与市场数据 | DashScope Streamable HTTP MCP |
| 连锁商业 / 茶饮洞察（8 项） | 连锁品牌、门店、商圈与茶饮市场洞察 | DashScope Streamable HTTP MCP |
| 旅游洞察（10 项） | 景区、客流、酒店与旅游市场数据分析 | DashScope Streamable HTTP MCP |
GitHub、Context7 和 Alibaba Cloud Ops 通过 .env 中的 ZHIKUN_MCP_SERVERS 配置。配置只会让服务进入可选列表，三个服务均默认关闭，必须由用户在 MCP 管理 页面手动启用。不要使用 MCP_SERVERS：该名称会与 Spring Boot 的 mcp.servers 配置绑定冲突。完整 JSON 模板见 .env.example，真实密钥不得提交到 Git。
| 服务 | 默认状态（配置后） | 工具白名单 |
|---|---|---|
| GitHub MCP Server | 默认关闭，需在管理页手动启用 | get_me、get_file_contents、search_code、list_branches、list_commits、list_pull_requests、pull_request_read；强制只读和 Lockdown 模式 |
| Context7 | 默认关闭，需在管理页手动启用 | resolve-library-id、query-docs |
| Alibaba Cloud Ops | 默认关闭，需在管理页手动启用 | ECS_DescribeInstances、ECS_DescribeRegions、ECS_DescribeSecurityGroups、OSS_ListBuckets、OSS_ListObjects |
# 仅示例占位符；请将真实值放入已被 Git 忽略的 .env
CONTEXT7_API_KEY=your-context7-api-key
ALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-id
ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret
GITHUB_TOOLS=get_me,get_file_contents,search_code,list_branches,list_commits,list_pull_requests,pull_request_read
GITHUB_READ_ONLY=1
GITHUB_LOCKDOWN_MODE=1
ALIBABA_CLOUD_OPS_VISIBLE_TOOLS=ECS_DescribeInstances,ECS_DescribeRegions,ECS_DescribeSecurityGroups,OSS_ListBuckets,OSS_ListObjects
# ZHIKUN_MCP_SERVERS=<从 .env.example 复制 JSON 模板>修改 .env 或外部 MCP 连接配置后需要重启；重启后还需在 MCP 管理 页面手动启用所需服务。之后在管理页启用或关闭服务无需再次重启。
本地外部服务还需要对应运行程序：GitHub wrapper 需要官方二进制或可用 Docker；Alibaba Cloud Ops wrapper 需要专用运行环境或 uvx。镜像已包含对应运行依赖；本地仅把 scripts/mcp 加到 PATH 或填写 Key 并不会安装它们。参见 GitHub wrapper 和 Alibaba wrapper。
管理员可在 configuration/mcp/mcp_capability_registry.json 中注册新的 MCP 工具。这里的 enabled 是工具白名单，不是用户服务开关：
{
"id": "mcp_your_tool",
"name": "你的工具名称",
"toolName": "mcp_server_tool_name",
"url": "https://your-mcp-server/mcp",
"transportType": "HTTP",
"domain": "your_domain",
"category": "MCP_TOOL",
"enabled": true
}- MCP Roots 范围声明：向服务声明工作区根；不构成对远端进程的操作系统沙箱
- MCP 长操作进度追踪：实时显示 MCP 工具执行进度，支持用户取消
- MCP Schema 智能压缩：自动压缩大型工具参数描述，减少 LLM 上下文占用
- MCP 服务级上下文隔离：关闭的服务不会建立连接、注册工具或向模型上下文注入 Schema
- MCP 失败处理：远端工具报告错误时保留失败状态及诊断；连接不可用、超时或调用异常时返回对应错误，不以历史成功结果替代。
| 客户端传输 | 典型连接方式 |
|---|---|
| STDIO | 启动本地子进程并通过标准输入输出通信 |
| SSE | 连接远端 SSE 服务 |
| HTTP | 连接远端 HTTP MCP 端点 |
| WebSocket | 连接 WebSocket MCP 服务 |
服务端在 mcp.server.enabled=true 时提供 /mcp HTTP JSON-RPC 入口；不能据此宣称四类服务端均已接通。STDIO 服务端类尚无启动调用方，WebSocket /app/mcp 属于界面管理通道。实现见 MCP 源码。
ZhikunCode 提供 40+ 内置工具，并支持 MCP、插件与平台条件工具动态扩展；最终可用集合以当前部署、Feature Flag 和已连接的 MCP Server 为准：
| 分类 | 工具 | 说明 |
|---|---|---|
| 文件操作 | Read、Write、Edit、NotebookEdit | 读取、写入、编辑文件（原子写入+SHA-256冲突检测），支持 Jupyter Notebook；Read 支持大图片自动外置化（>50KB 转 JSON 引用，由 ImageRefInjector 按需注入） |
| 代码搜索 | Grep、Glob、ToolSearch、LSP、Snip | 正则搜索、文件匹配、工具搜索、LSP 语言服务（含调用层级分析）、代码片段、智能分层搜索（作用域感知 4 层优先级路由） |
| 命令执行 | Bash、PowerShell、REPL | Shell 执行（授权、动态超时分类与受控恢复提示；可选沙箱不覆盖全部路径，不自动重试）、Windows PowerShell、交互式 REPL 会话 |
| Git 操作 | Git、Worktree | Git 命令执行、Worktree 管理 |
| Web 工具 | WebSearch、WebFetch、WebBrowser | 网络搜索、网页抓取、浏览器自动化 |
| Agent 委派 | Agent | 五种角色、独立上下文、并行执行、同步或后台结果回收 |
| 任务管理 | TaskCreate、TaskGet、TaskList、TaskUpdate、TaskStop | 当前会话的后台执行、状态与结果查询、输出更新和取消请求 |
| 交互 | AskUserQuestion、Brief、Sleep、TodoWrite | 用户提问、基础上下文展示、等待、任务清单；多选问题须显式设置 multiSelect |
| 定时任务 | CronCreate、CronList、CronDelete | 定时任务管理 |
| 计划工具 | EnterPlanMode、ExitPlanMode、VerifyPlanExecution | EnterPlanMode／ExitPlanMode 尚未接入权限切换，返回 PLAN_MODE_UNAVAILABLE；VerifyPlanExecution 提供文件、内容与命令结果检查 |
| 配置 | Config、SyntheticOutput | 配置管理、合成输出 |
| 监控 | Monitor、CtxInspect、TerminalCapture | 系统监控、上下文检查、终端输出捕获 |
| 验证 | VerifyJourney | 浏览器交互或 HTTP API 断言；auto 按步骤为整次旅程选择验证器，不是任意混合步骤切换。需运行验证开关与对应 Python 能力就绪 |
| MCP 扩展 | MCP 工具适配器 | 连接外部 MCP 服务（动态注册） |
PLAN 权限模式仍然可用，与计划面板相互独立。/plan 和 /plan on [名称] 显示前端计划面板，/plan off 隐藏面板；这些命令不会改变会话权限。EnterPlanMode／ExitPlanMode 工具也不会切换权限、提交审批或展示计划文件。
后台任务的创建、查询、输出更新与取消流程，以及它们和 TodoWrite 的用途区别，见上文“Agent 委派与后台任务”。
Edit 更新已有文件时要求非空匹配；已有空文件请用 Write 填入内容。不存在的文件仍可通过 Edit 的空 old_string 创建。
ZhikunCode 提供多种可视化能力，展示 AI 编程过程中的数据和状态：
| 功能 | 说明 |
|---|---|
| Mermaid 图表渲染 | AI 回复中的 mermaid 代码块自动渲染为交互式矢量图，支持复制 SVG / 下载 PNG |
| API 序列图 | 自动从会话中提取工具调用记录，生成 Mermaid 序列图，支持过滤和详情查看 |
| Git 时间线 | 可视化 Git 提交历史，支持 Diff 查看和 Blame 视图，commit 类型自动着色 |
| 工具进度可视化 | 工具执行过程显示进度条、ETA 预估和迷你日志查看器 |
| 文件树导航 | 侧边栏项目文件树，支持搜索过滤、虚拟滚动、文件类型图标 |
| 代码复杂度 Treemap | 基于 recharts 的交互式矩形面积图，面积映射代码行数(LOC)，颜色映射风险等级(A-E)，支持钻取导航、语言/风险过滤、统计卡片，Python radon + tree-sitter 多语言分析 |
| 变更影响链路 | 基于 @xyflow/react 的 DAG 可视化，展示代码变更的影响传播路径，LibCST 精准解析 Python 调用图，BFS 逐层传播分析，节点类型/置信度/影响层级一目了然 |
| API 契约可视化 | 合并 ZhikunCode 自身运行中的 Java + Python 双端 OpenAPI 规范（不自动推断任意用户项目的接口），端点列表按 Tag 分组、HTTP 方法颜色编码、Schema 递归展示，支持 All/Java/Python 数据源切换 |
| 代码→图表自动生成 | 输入代码文件路径自动生成 Mermaid 时序图/流程图，Python LibCST + tree-sitter 多语言解析，调用链 BFS 遍历自动识别 Controller/Service/Repository 参与者，五维置信度评分(0-1)，Monaco Editor 实时编辑源码，SVG 复制 / PNG 下载导出，支持 1-5 级遍历深度控制 |
| 代码路径追踪可视化 | 基于 @xyflow/react 的静态代码调用路径可视化，Python CodePathTracer 正向 BFS 遍历 + 六层分层标注（Controller/Service/Repository/Database/External/Utility），dagre TB 布局算法自动排列节点，自定义 LayerNode 按层级着色，MiniMap 全局导览 + LayerStatsBar 层级统计，支持 API 端点扫描、参数追踪、节点点击详情、maxDepth 深度控制，通过侧边栏"代码路径" Tab 进入 |
| 运行时验证进度面板 | JourneyVerifyPanel — 实时显示验证步骤执行状态（waiting/executing/passed/failed）、STOMP 推送进度、证据链关联 |
| RV-4 证据包查看器 | 查看已保存的 screenshot / command / console / test / video / har / diff 等证据类型，实际产出依步骤与环境而定；移动证据审批尚未完整接通。REST 入口提供证据查询与 Blob 下载：GET /api/evidence/{bundleId}、GET /api/evidence/session/{sessionId}、GET /api/evidence/blob/{sha256} |
| Activity Panel 活动面板 | 三层卡片展示（L1 紧凑 → L2 展开 → L3 Portal），实时显示工具执行状态、Signal 风险标记、审批决策状态 |
/visualize通过 VisualizationAutoRouter 推送 mermaid／json／text。分析页面可从侧边栏进入；部分页面依赖 Python 服务及前端同源代理，基础 Docker 部署不能保证全部可用。调用图包含语言相关解析与启发式分析，置信度不等于准确率，也不是完整运行时追踪。
验证时可要求模型打开实际页面完成指定操作，或调用 VerifyJourney 对接口状态／JSONPath 作断言，再检查工具结果和留存证据。自动模式为整次旅程选择浏览器或 HTTP 验证器；证据存储成功与测试行为通过是不同结果。
主对话使用用户选择的模型；子 Agent 按显式 model → 父查询模型 → premium 别名解析模型。快速查询与压缩摘要使用各自配置：快速查询默认百炼 deepseek-v4.1-flash，压缩摘要默认 DeepSeek 官方直连 deepseek-flash；只有当前模型不支持图片时才触发视觉兜底。百炼与 DeepSeek 直连的模型 ID、端点和 Key 独立。
百炼 V4.1 Flash 的流式请求、快速查询和压缩摘要统一发送 thinking.type=enabled、字符串 reasoning_effort="max"；DeepSeek 官方直连的流式请求与压缩摘要同样发送该参数组合（chatSync 非流式快速查询不注入 thinking）。2026-09-15 Token Plan 实测接受 "max"、拒绝整数；未验证内部数值映射。
配置模板在 .env.example，完整默认值和开关以 application.yml 与 ModelRegistry 为准。手动启动时需显式加载 .env，Docker 只传入 Compose 列出的变量；写入 .env 不等于已进入进程。修改启动配置后重启对应服务。
多 Provider 配置（推荐）：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
LLM_PROVIDER_OPENAI_API_KEY |
— | 空 | OpenAI 官方直连 API Key；留空不注册此 Provider |
LLM_PROVIDER_OPENAI_MODELS |
— | gpt-6-astra | 官方直连模型列表（逗号分隔）；与 ZenMux 的 openai/gpt-6-astra 分开路由 |
LLM_PROVIDER_DASHSCOPE_API_KEY |
— | — | 千问/DashScope API Key |
LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_API_KEY |
— | — | 阿里云百炼 Token Plan 专属 API Key |
LLM_PROVIDER_DEEPSEEK_API_KEY |
— | — | DeepSeek API Key |
LLM_PROVIDER_MOONSHOT_API_KEY |
— | — | Moonshot/Kimi API Key |
LLM_PROVIDER_KIMI_CODE_API_KEY |
— | — | Kimi Code 订阅 API Key；留空不注册订阅渠道 |
LLM_PROVIDER_KIMI_CODE_MODELS |
— | k3.1-pro-highspeed,kimi-for-coding | Kimi Code 订阅模型列表；权限与额度取决于账号 |
LLM_PROVIDER_ZHIPU_API_KEY |
— | — | 智谱 GLM API Key |
LLM_PROVIDER_OPENROUTER_API_KEY |
— | — | OpenRouter API Key；留空不注册此 Provider |
LLM_PROVIDER_OPENROUTER_MODELS |
— | openrouter/anthropic/claude-fable-5.1 | OpenRouter 可用模型列表（逗号分隔） |
LLM_DEFAULT_MODEL |
— | deepseek-v4.1-flash | 默认模型（百炼 Token Plan）；不可用时回退到当前 Provider 的有效默认模型 |
LLM_FAST_MODEL |
— | deepseek-v4.1-flash | 快速辅助查询与分类器回退优先使用的模型 |
LLM_COMPACT_MODEL |
— | deepseek-flash | 对话压缩摘要模型（DeepSeek 官方直连），独立于快速模型选择 |
LLM_COMPACT_PROVIDER |
— | deepseek | 压缩摘要 Provider；需已注册该 Provider，配合 LLM_COMPACT_MODEL 使用 |
LLM_VISION_FALLBACK_MODEL |
— | deepseek-v4.1-flash | 当前模型不支持图片时优先使用的视觉模型 |
前端可切换已配置且可用的 Provider。当前 Docker 入口只检查 OpenAI、DashScope、Token Plan、DeepSeek、Moonshot、Zhipu、ZenMux 或旧式 Key；仅 Kimi Code、MiniMax、OpenRouter Key 时会退出，可先按本地三服务启动。
OpenAI Docker 配置回归：python3 scripts/test-openai-docker-config.py（需 Python 3、Bash、Docker Compose；使用假 key，不读取本地 .env，不启动容器或调用模型）。
WebSearch 配置（本地启动与 Docker Compose 均支持）：
| 变量 | 默认值 | 说明 |
|---|---|---|
WEB_SEARCH_BACKEND |
auto | auto：已连接的 MCP zhipu-websearch → disabled；deepseek：显式启用 DeepSeek；也支持 mcp、disabled |
WEB_SEARCH_DEEPSEEK_API_KEY |
空 | 专用 Key；未设置、空串或仅空白时复用 LLM_PROVIDER_DEEPSEEK_API_KEY |
WEB_SEARCH_DEEPSEEK_BASE_URL |
https://api.deepseek.com | API 根地址，不附加 /v1 或 /v1/tools/search；未设置或空白时使用默认值 |
设置 WEB_SEARCH_BACKEND=deepseek 并重启后启用收费搜索；auto 不会因存在 DeepSeek Key 自动启用它，调用失败也不自动切换后端。选定的 Key 来源按逗号拆分、trim、去空后固定使用首项，不参与 LLM Key 轮换；非空白专用值若没有可用项（如 ,,）则禁用搜索。
DeepSeek 仅接入 Search，include_content 默认关闭。收到 HTTP 408、429、500–599 时最多 3 次尝试（含首次），单次请求 45 秒超时；可解析的 Retry-After 与本地退避取较大值，单次等待超过 30 秒或无法解析时停止重试，不提前重发。重试产生的等待会计入整个工具调用的实际耗时，但不占用单次请求的超时。
OpenRouter / Claude Fable 5.1： 在 .env 中填写 LLM_PROVIDER_OPENROUTER_API_KEY，重启服务后从模型列表选择 Claude Fable 5.1（OpenRouter）（openrouter/anthropic/claude-fable-5.1）。如需设为默认模型，增加 LLM_DEFAULT_MODEL=openrouter/anthropic/claude-fable-5.1。本地启动与 Docker Compose 均支持上述变量。
本次模型目录精简由项目主动进行，不表示供应商下架。OpenRouter Provider 默认模型从免费预览的 Union Alpha 改为收费的 Claude Fable 5.1，仅影响使用该 Provider 默认回退的请求；全局 app.model.default 与 LLM_DEFAULT_MODEL 的默认值仍为百炼 deepseek-v4.1-flash。实际计费以服务商账单为准。
接入复用现有 llm.providers.* → MultiProviderConfiguration → OpenAiCompatibleProvider 链路，端点为 https://openrouter.ai/api/v1，沿用流式输出、图片输入、工具调用和 Key 轮换。能力由 ModelRegistry 统一提供给 /api/models，无需新增前端分支。
OpenRouter 强推理模型与渠道隔离：
| 界面名称 | ZhikunCode 模型 ID | 上游模型 ID | 上下文 / 最大输出 |
|---|---|---|---|
| Claude Fable 5.1（OpenRouter） | openrouter/anthropic/claude-fable-5.1 |
anthropic/claude-fable-5.1 |
1,000,000 / 128,000 |
Claude Fable 5.1 使用已有 OpenRouter Key，默认请求 reasoning.effort=max、exclude=false，不受通用 thinking 关闭开关降档；这是仓库注册与请求配置，账号可用性和上游规格需向服务商核实。上下文按注册表窗口配置，仍保留现有输出预留、压缩阈值和安全余量。单次输出预算由现有运行配置决定，上表是仓库登记上限，并非对服务商规格的独立保证，也非每次都生成该长度。
内部 ID 的 openrouter/ 前缀只用于路由、能力、会话与重试隔离，发送请求时去掉；现有 ZenMux 的 openai/gpt-6-astra、anthropic/claude-fable-5.1 路由保持不变。OpenRouter 的模型列表若填写官方原始 ID anthropic/claude-fable-5.1，启动时也会自动规范化并去重，避免注册顺序决定渠道。其他重复 ID 明确拒绝歧义路由。
流式 thinking 使用现有展示事件；reasoning_details（含签名/加密数据）按原序保存，并仅对同 Provider、同模型的后续请求回传，切换渠道或模型不复用。费用展示采用仓库登记的参考价格，实际计费以账号和服务商账单为准。
原配置记录日期：2026-09-17；模型与服务商页面可能变化。参考：Fable、Reasoning 文档。
单 Provider 配置（向后兼容）：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
LLM_API_KEY |
✅ | — | LLM 服务商的 API Key |
LLM_BASE_URL |
— | DashScope | LLM API 地址 |
LLM_DEFAULT_MODEL |
— | qwen3.8-max-0902 | 默认模型 |
LLM_MODELS |
— | 千问系列 | 可用模型列表（逗号分隔） |
如所有
LLM_PROVIDER_*_API_KEY的值均为空，系统自动回退到单 Provider 模式；示例占位值也需清空。
通用配置：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
ZHIKUN_PORT |
— | 8080 | Docker 映射的宿主机端口 |
SPRING_PROFILES_ACTIVE |
— | production | Spring 配置文件 |
JAVA_OPTS |
— | -Xms256m -Xmx1024m | JVM 参数 |
WORKSPACE_PATH |
— | ./workspace | 挂载到容器的工作目录 |
ZHIKUN_DEFAULT_WORKSPACE |
— | 服务进程目录；./start.sh 为仓库根 |
非 Web 客户端未指定 Project 时的服务端兜底目录，不自动授予普通编辑权限 |
ZHIKUN_WORKSPACE_ALLOWED_ROOTS |
— | 空 | 允许登记和浏览的服务端根目录，多个目录用逗号分隔；远程登记时必须配置 |
ZHIKUN_LOCAL_PICKER_ENABLED |
— | false（后端）；true（./start.sh 且两个相关变量均无非空配置） |
仅供直连本机桌面服务浏览本机文件系统；显式 false 和 allowed roots 配置均会保留，反向代理和生产部署应保持关闭并配置 allowed roots |
ZHIKUN_GLOBAL_DB_PATH |
— | ~/.config/ai-code-assistant/global.db |
Project 授权和全局配置数据库文件路径 |
ZHIKUNCODE_DATABASE_PROJECT_ROOT |
— | Project 工作目录 | Session 数据库根目录；Docker Compose 固定为 /app/data |
ALLOW_PRIVATE_NETWORK |
— | true（Docker） | 放行所有到达后端的来源，并非仅私网；远程部署见安全章节 |
LOG_DIR |
— | /app/log | 容器内日志目录 |
MCP_REGISTRY_PATH |
— | 自动配置 | MCP 能力注册表文件路径 |
高级配置：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
FEATURE_BACKGROUND_AGENT_WAIT |
— | true | 等待并汇总当前父 Run 的后台 Agent 结果；设为 false 关闭 |
AGENT_TIMEOUT_MAX_WAIT_MINUTES |
— | 31 | 每批后台 Agent 结果的等待预算，单位分钟；不修改子 Agent 执行超时 |
ZHIKUN_COORDINATOR_MODE |
— | 0 | Feature flag，启用协调器模式（0=关闭，1=开启） |
ZHIKUN_DELETE_CONFIRM_CODE |
— | 空 | 删除会话二次确认验证码；配置后 Web 删除会话须输入该验证码，未配置保持原确认流程 |
LLM_PROVIDER_DASHSCOPE_MODELS |
— | qwen3.8-max-0902 | 按量计费 DashScope 可用模型列表（逗号分隔；实际目录可动态扩展） |
LLM_PROVIDER_DASHSCOPE_TOKEN_PLAN_MODELS |
— | qwen3.8-max,qwen3.8-flash,deepseek-v4.1-flash,bailian/glm-5.3 | 百炼 Token Plan Provider 可用模型列表；与普通 DashScope、DeepSeek 直连配置相互独立 |
LLM_PROVIDER_DEEPSEEK_MODELS |
— | deepseek-flash | DeepSeek 可用模型列表；默认使用 V4.1 Flash（逗号分隔） |
LLM_PROVIDER_MOONSHOT_MODELS |
— | kimi-k3.1-pro-highspeed | Moonshot 可用模型列表（逗号分隔） |
LLM_PROVIDER_ZHIPU_MODELS |
— | glm-5.3,glm-5.3-flash | 智谱 GLM 可用模型列表（逗号分隔） |
上述两个后台等待变量需进入后端进程环境；Docker 部署须通过 Compose override 的 environment 显式传入，仅写入项目 .env 不会自动透传。
上下文管理配置（application.yml）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
context.cascade.incremental-collapse.enabled |
true | 启动时决定是否注册 IncrementalCollapseManager；设为 false 时禁用该组件触发的增量折叠，修改后需重启 |
context.cascade.incremental-collapse.segment-turns |
10 | YAML 声明值；实际 10 轮来自代码常量 |
context.cascade.incremental-collapse.session-timeout-minutes |
30 | YAML 声明值；当前跟踪状态的 30 分钟清理条件来自代码常量，不是任务超时 |
features.flags.CACHED_MICROCOMPACT |
true | 控制系统提示中的微压缩说明段，不关闭实际 ContextCascade 微压缩 |
features.flags.TOKEN_BUDGET |
false | 控制系统提示中的预算说明段，不代表 TokenBudgetGuard 默认关闭 |
features.flags.SELF_CORRECTION_LOOP |
false | 执行失败自动诊断修复循环（编译错误/测试失败，最多重试3次） |
features.flags.PRECISE_TOKENIZER |
false | 精确 Token 计数（调用 Python tiktoken，替代字符估算） |
features.flags.GIT_DIFF_TRACKER |
false | Git 变更追踪与编辑历史聚合 |
features.flags.SEARCH_STRATEGY_ROUTER |
false | 作用域感知分层搜索策略路由 |
RUNTIME_VERIFICATION |
true | 启用运行时验证框架（开启后前端显示验证进度面板，需同时配合 BROWSER_AUTOMATION 或 HTTP_API 能力域） |
通过 FeatureFlagService 读取的功能开关，可用后端进程环境变量 FEATURE_<大写键名> 覆盖 features.flags 中的对应值，例如 FEATURE_PRECISE_TOKENIZER=true；此规则不适用于任意配置项。手动启动需先加载环境变量，Docker 则需在 Compose 的 environment 中显式传入；仅写入根 .env 不会自动透传。修改后重启后端生效。
默认资源配置（可在 docker-compose.yml 中调整）：
| 配置项 | 默认值 |
|---|---|
| 内存上限 | 4GB |
| 内存预留 | 1GB |
| 健康检查间隔 | 30s |
| 启动等待时间 | 60s |
首次构建同时涉及 Maven 与前端构建；若出现内存不足，按构建日志增加 Docker 可用内存。表中为 Compose 声明值，实际限制取决于运行环境是否应用该配置。
| 现象 | 先检查什么 |
|---|---|
| 构建／启动失败 | JDK 21、Node 版本（见本地安装）、依赖下载；Docker 看 docker compose logs --tail=100 zhikuncode，手动启动看各终端 |
| Key 无效／没有工具调用 | 选择的 Provider 与模型、实际服务商错误、Docker 入口支持范围和模型工具调用能力 |
| 端口占用 | 先识别 8080／8000／5173 的监听进程；不要终止不属于本次启动的服务 |
| 找不到项目／挂载不可写 | 本地使用真实路径；Docker 选择容器路径，检查宿主卷权限和 Docker Desktop 文件共享 |
| Python 活着但能力不可用 | /api/health/capabilities 中的 available／reason、实际解释器、依赖和 Chromium |
| 页面断线／审批未出现 | WebSocket 代理与服务日志；重连恢复过程，默认完全访问可能不弹审批，后端重启则旧运行中断 |
使用 start.sh 时日志位于 log/backend-console.log、log/python-console.log、log/frontend-console.log。Compose 的 zhikun-data 卷保存 /app/data 下的会话和全局配置，zhikun-memory 卷保存 /app/.ai-code-assistant 下的个人记忆及受信任设备文件，项目来自独立挂载；停服一致备份应同时覆盖这两个卷和项目挂载，保留数据时不要执行 docker compose down -v。错误信息中先移除凭证再分享。
Q1：支持哪些大模型？
提供 OpenAI 兼容接口接入路径和多 Provider 配置，例如：
- 千问 / DashScope（国内直连，默认推荐）
- DeepSeek（国内直连）
- Moonshot / Kimi（国内直连）
- 智谱GLM（国内直连）
- MiniMax（国内直连）
- OpenAI gpt-5.6-sol / gpt-5.4-mini（需外网访问）
- Anthropic Claude（通过 OpenAI 兼容 API）
- 本地模型（通过 Ollama、vLLM 等）
配置 LLM_BASE_URL、LLM_API_KEY 和模型 ID 后仍需验证兼容性，尤其工具调用、流式输出、图片和推理字段；兼容协议名称不保证每个模型能力都可用。
Q2：Docker 部署需要什么配置？
最低要求：
- Docker 20.10+
- Docker Compose V2
- 4GB+ 可用内存
- 网络能访问 LLM API 端点（用千问的话国内网络就行）
部署只需 3 步：
git clone https://github.com/zhikunqingtao/zhikuncode.git && cd zhikuncode
cp .env.example .env # 编辑填入 API Key
docker compose up -d --build # 构建并启动打开 http://localhost:8080 即可使用。
Q3：数据存在哪里？安全吗？
应用状态和数据库保存在本地；提示词、相关代码上下文和其他模型输入会发送给你配置的 LLM 服务商：
- 会话数据 — SQLite 数据库，存储在 Docker Volume
zhikun-data中 - 个人记忆与设备信任 —
MEMORY.md、其.bak备份及trusted-devices.json位于 Docker Volumezhikun-memory的/app/.ai-code-assistant；备份按应用私有数据保管，不将设备信任文件分享给其他部署 - 项目代码 — 通过 Volume 挂载你本地的项目目录
- API Key — 由部署环境和配置管理；排查日志或分享资料前应移除凭证
旧授权数据库升级边界： 当前 V015 持久交互与 V019 授权表不保证兼容旧版授权 schema，旧权限不会自动转成当前 Grant。旧表可能缺少必需列或与新表同名，迁移校验失败会阻止启动。升级前应停止应用并一致备份项目库、全局库及相关数据，先在隔离副本验证目标版本迁移与启动；不兼容时停止升级、保留原库，采用经过验证的迁移方案后重新授权。项目库也保存会话和消息，不能直接删库或无条件重建；只有明确可丢弃的开发库才适合重建。
已验证兼容后的存储路径迁移： 新卷不会自动接收旧容器可写层的数据。先完成上述兼容性验证，再停止应用并备份；数据库与个人记忆须分别恢复，不能把整个旧主目录统一复制到数据库目录。使用默认 Compose 路径时：
| 旧数据／备份中的文件 | 当前恢复目标 | 持久化位置 |
|---|---|---|
旧 /app/.ai-code-assistant/data.db 及同次备份的 SQLite 伴随文件 |
/app/data/.ai-code-assistant/data.db 及对应伴随文件 |
zhikun-data |
旧 /app/.config/ai-code-assistant/global.db 及同次备份的 SQLite 伴随文件 |
/app/data/global.db 及对应伴随文件 |
zhikun-data |
/app/.ai-code-assistant/MEMORY.md、MEMORY.md.bak |
同名文件，仍在 /app/.ai-code-assistant/ |
zhikun-memory |
/app/.ai-code-assistant/trusted-devices.json |
同名文件，仍在 /app/.ai-code-assistant/ |
zhikun-memory |
已使用 /app/data 的部署应保留该卷现有数据库，不用旧主目录中的数据库覆盖它。项目挂载中的数据也应另行备份。以下命令从仓库根目录的同一个 Bash 会话执行，只选择实际存在的源路径；复制失败时停止排查，不能将权限或 I/O 错误当作“文件不存在”跳过。全程不要执行 docker compose down -v。
set -e
umask 077
mkdir -p "$HOME/zhikuncode-backups"
migration_backup=$(mktemp -d "$HOME/zhikuncode-backups/backup.XXXXXX")
docker compose stop zhikuncode
docker cp zhikuncode:/app/data "$migration_backup/data"
docker cp zhikuncode:/app/.ai-code-assistant "$migration_backup/home"
# 仅旧版全局数据库仍在此路径时执行；备份整个目录以保留伴随文件：
# docker cp zhikuncode:/app/.config/ai-code-assistant "$migration_backup/legacy-config"确认备份完整且可恢复后，构建目标镜像。下面是逐文件恢复模板，示例恢复个人记忆；数据库文件应按上表选择路径，并在应用仍停止时恢复同次备份中的 -wal、-shm、-journal（若存在），不可混用不同时间的数据库与伴随文件。已有新卷内容不会被自动覆盖：目标存在时模板退出，须保留双方副本、人工核对，不要删除目标来绕过检查。
docker compose build zhikuncode
restore_source=home/MEMORY.md
restore_target=/app/.ai-code-assistant/MEMORY.md
docker compose run --rm --no-deps -T --user root --entrypoint sh \
--volume "$migration_backup:/migration-backup:ro" \
--env RESTORE_SOURCE="$restore_source" --env RESTORE_TARGET="$restore_target" \
zhikuncode -ec '
src="https://raw.githubusercontent.com/zhikunqingtao/zhikuncode/HEAD/migration-backup/$RESTORE_SOURCE"
dst="$RESTORE_TARGET"
test -f "$src"
if [ -e "$dst" ] || [ -L "$dst" ]; then
echo "Refusing to overwrite existing restore target: $dst" >&2
exit 1
fi
umask 077
dir=$(dirname "$dst")
mkdir -p "$dir"
set -C
cat "$src" > "$dst"
chown zhikun:zhikun "$dir" "$dst"
'
# 全部所需文件恢复成功并核对后，才重建和启动应用容器：
docker compose create --force-recreate zhikuncode
docker compose start zhikuncode恢复容器仅运行上述 shell，不启动应用，备份挂载为只读；文件属主按目标镜像中的 zhikun 用户设置，不假定固定数字 UID。任一步失败时保持应用停止并保留备份。确认 Session、配置、个人记忆和设备信任状态均符合预期后，再按自己的备份保留策略处置备份。
实际请求发往你配置的模型／MCP／云服务端点；如果选择聚合 Provider 或代理，请求也会经过该渠道。自托管不代表所有输入只留在本地。
Q4：支持内网 / 离线部署吗？
可以部署在内网；使用云模型、联网搜索、MCP 或发布时仍需访问相应端点。完全离线还需提前准备构建依赖、模型和运行资源，并验证所选模型的工具调用兼容性。
- 使用国产模型（千问/DeepSeek）： 国内网络直连，无需科学上网
- 本地模型： 可配置 Ollama 的兼容端点；例如 Docker Desktop 下宿主服务为
http://host.docker.internal:11434/v1，Linux 需另行配置宿主地址。是否适合当前任务需实际验证 - 企业内网： 只需确保服务器能访问 LLM API 端点即可
Q5：Agent 委派与后台任务怎么用？
在对话中说明任务、分工范围和预期结果，例如：
“让两个 explore Agent 并行调查认证接口和前端登录流程，分别给出文件位置与风险；你汇总结论后提出修改方案。实现完成后，再让 verification Agent 执行已授权的测试并报告证据。”
主 Agent 可同步等待子任务，或通过 run_in_background=true 在推进其他工作后收集当前 Run 的结果。需要隔离文件修改时可指定 isolation=worktree，执行基于已提交 HEAD 的独立工作区，并在安全检查通过后合回。
需要持续查询的后台执行，可要求“用 TaskCreate 运行测试，随后用 TaskGet 查询结果”；取消时按该任务 ID 使用 TaskStop，并查询停止是否确认。TodoWrite 用于计划清单。具体角色、模型选择与交付边界见上文“Agent 委派与后台任务”。
Q6：和 VS Code 插件（Copilot/Cline）冲突吗？
不冲突。 ZhikunCode 是独立的 Web 应用，不依赖任何 IDE，不需要安装插件。
你可以同时使用：
- VS Code + Copilot —— 做行级代码补全
- ZhikunCode —— 做对话式 Agent 编程、复杂任务编排
两者可并用；同时修改同一项目时应协调文件范围，避免覆盖彼此改动。
Q7：怎么贡献代码？
欢迎贡献！详细流程见 CONTRIBUTING.md。
简单步骤：
- Fork 仓库
- 创建功能分支 (
git checkout -b feature/your-feature) - 提交代码
- 创建 Pull Request
推荐从标记为 good first issue 的 Issue 开始。
开发环境需要： JDK 21、Node.js 22.x（至少 22.13）或 24+、Python 3.11~3.12、Maven 3.9+
Q8：为什么选择 Java + React + Python 三端架构？
每种技术选型都有明确的理由：
-
Java 21 + Spring Boot（后端）：
- 强类型 + 成熟的企业级生态，代码可维护性强
- Spring WebSocket 原生支持实时通信
- Virtual Thread（虚拟线程）天然适合多 Agent 并发执行
- 企业 IT 团队容易接受和部署
-
React 18 + TypeScript（前端）：
- 组件化开发，状态管理成熟（Zustand）
- TypeScript 提供类型安全
- Vite 构建速度快，开发体验好
- TailwindCSS 实现高效的 UI 开发
-
Python FastAPI（分析服务）：
- Python 生态在代码分析、AST 解析方面成熟
- FastAPI 异步性能好
- 作为独立服务，不影响主后端的稳定性
Q9：Docker 部署遇到问题怎么排查？
容器启动后显示 unhealthy：
# 查看容器状态
docker ps -a
# 查看启动日志（Java 启动通常需要 30-60 秒）
docker logs zhikuncode
# 查看健康检查详情
docker inspect --format='{{json .State.Health}}' zhikuncode | python3 -m json.tool常见启动失败原因：
LLM_API_KEY is not configured— 未配置 API Key，请检查 .env 文件Unable to access jarfile— 镜像构建不完整，尝试docker compose up --build- 内存不足 — 默认需要 4GB，可在 docker-compose.yml 中调整
deploy.resources.limits.memory
查看运行时日志：
# 实时跟踪日志
docker logs -f zhikuncode
# 进入容器查看日志文件
docker exec -it zhikuncode ls -la /app/log/
docker exec -it zhikuncode tail -100 /app/log/app.log关于 ALLOW_PRIVATE_NETWORK：
当前镜像默认 true 会放行所有到达后端的来源；容器网络不能替代入口认证。请按安全章节配置认证、TLS、端口绑定和代理边界。设为 false 需通过 Compose 显式传入，之后仍要核对认证行为。
调整 JVM 内存：
在 .env 中设置：
JAVA_OPTS="-Xms512m -Xmx2048m --enable-preview"Q10：8080 端口被占用怎么办？
修改 .env 文件中的端口配置：
ZHIKUN_PORT=9090 # 改为任意未被占用的端口然后重新启动：
docker compose down
docker compose up -d访问 http://localhost:9090 即可。
继续阅读：案例资料 · 系统架构图 · 能力总览 · 会话合并设计 · 安全问题报告。
我们欢迎任何形式的贡献 —— Bug 修复、新功能、文档改进都可以。
详见 CONTRIBUTING.md。
本项目使用 MIT License 开源协议。
- 邮箱： [email protected]
- GitHub Issues： 提交问题
如果这个项目对你有帮助，欢迎点个 Star ⭐
用 ❤️ 和 AI 构建
