Claude Code Java

基于 Spring AI 2.0.0 + Spring Boot 4.1 + Java 21 复刻的 Claude Code 风格 Agent。

本项目对照 Claude Code v2.1.88 的 TypeScript 源码（逆向分析报告），用 Java 重新实现了 Claude Code 的核心架构，包括工具系统、权限控制、上下文压缩、Hook、MCP、子代理、计划模式、定时任务、LSP 集成等。

快速开始

环境要求

• Java 21（LTS）
• Maven 3.9+
• API Key：Anthropic（ANTHROPIC_API_KEY）或 OpenAI（OPENAI_API_KEY）

构建与运行

# 设置 JDK 21
export JAVA_HOME=/path/to/jdk-21

# 编译全部模块
mvn clean install -DskipTests

# 运行测试（246 项，含 Phase 0-7 新增 95 项）
mvn -pl ccc-test test

# 启动 REPL（需配置 API Key）
export ANTHROPIC_API_KEY=sk-ant-xxx
mvn -pl ccc-app spring-boot:run

配置

配置文件按优先级合并（从低到高）：

文件	作用域
~/.claude/settings.json	用户级
.claude/settings.json	项目级
.claude/settings.local.json	本地级（不提交版本控制）

环境变量覆盖：CCJ_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY / CCJ_PROVIDER / CCJ_MODEL

CLAUDE.md 指令文件自动发现（从 root 到 cwd 遍历）：CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md、CLAUDE.local.md

工程结构

28 个 Maven 模块，分层对应 Claude Code 源码：

claude-code-java/
├── ccc-core          核心抽象：Tool 接口、Message 类型、Session、PermissionMode + CleanupRegistry
├── ccc-config        配置系统：settings.json 三级合并 + SettingsCache + SettingsValidator + SettingsWatcher + MDM 企业托管
├── ccc-auth          认证：API Key 凭据存储、DeviceID
├── ccc-prompt        系统提示词：分层组装 + CLAUDE.md 注入
├── ccc-models        模型层：Anthropic + OpenAI Chat + OpenAI Response 自封装适配器 + ForkedAgent
├── ccc-tools         工具实现：Read/Edit/Write/Glob/Grep/Bash/PowerShell/WebFetch/WebSearch/NotebookEdit/Config/Skill/ToolSearch/REPL + 执行管线
├── ccc-permission    权限系统：7 层责任链 + 6 模式策略 + Bash 安全 6 层 + 沙盒
├── ccc-context       上下文管理：CompactingChatMemory + MicroCompactor + TokenEstimator
├── ccc-hooks         Hook 系统：28 种事件 + 4 类执行器 + SSRF 防护
├── ccc-mcp           MCP 客户端：薄封装 spring-ai-starter-mcp-client
├── ccc-mcp-server    MCP Server 入口：把自身工具暴露为 MCP server（stdio transport）
├── ccc-skills        Skills 系统：frontmatter 解析 + 触发词匹配（实现 SkillLookup SPI）
├── ccc-memory        自动记忆系统：memdir + side-query 选择 + forked agent 提取
├── ccc-plan          Plan Mode V2：4 阶段状态机 + allowedPrompts 预授权
├── ccc-cron          Cron 调度器：5 字段解析 + 1s 轮询 + 进程锁 + 抖动
├── ccc-lsp           LSP 集成：lsp4j 客户端 + 9 操作工具 + 诊断 LRU 缓存
├── ccc-tasks         子代理：AgentTool + CoordinatorMode + Task 工具
├── ccc-commands      斜杠命令：10 个核心命令
├── ccc-repl          终端 REPL：JLine3 主循环 + 消息渲染 + Footer
├── ccc-filehistory   文件历史：编辑前快照（hardlink）+ /rewind 回溯
├── ccc-outputstyles  输出风格：.md 加载 + frontmatter + 注入 system prompt
├── ccc-vim           Vim 模式：11 状态有限状态机 + operator + motion + text object
├── ccc-keybindings   快捷键系统：18 上下文 + chord 前缀检测 + 平台感知 + 热重载
├── ccc-worktree      Git Worktree：EnterWorktree/ExitWorktree 会话隔离
├── ccc-swarm         多 Agent 组队：InProcess 虚拟线程后端 + 文件邮箱 + Leader 权限桥
├── ccc-app           Spring Boot 启动 + 装配 + REPL 入口 + autoUpdater（GitHub Releases）
└── ccc-test          集成测试：246 项测试覆盖全部核心功能（原 151 项 + Phase 0-7 新增 95 项）

核心功能

三供应商模型层

供应商	实现方式	端点
Anthropic	原生 spring-ai-anthropic	/v1/messages
OpenAI Chat	原生 spring-ai-openai	/v1/chat/completions
OpenAI Response	自封装完整适配器	/v1/responses

OpenAI Response API 适配器实现了 Spring AI 的 ChatModel + StreamingChatModel 接口，用 WebClient 调 /v1/responses，解析 SSE 流，映射 function_call 到 Spring AI 的 ToolCall，reasoning summary 到 thinking metadata。

工具系统

• 16+ 个内置工具：Read、Edit、Write、Glob、Grep、Bash、PowerShell、TodoWrite、WebFetch、WebSearch、NotebookEdit、Config、Skill、ToolSearch、REPL、AskUserQuestion + Agent/Task/Cron/Worktree/Swarm 工具
• StreamingToolExecutor：基于 isConcurrencySafe 的并发控制（只读工具并行，写入/交互工具串行，无硬编码上限）
• 8 步执行管线：inputSchema 校验 -> validateInput -> PreToolUse Hook -> 权限检查 -> tool.call -> PostToolUse Hook -> 格式化

权限系统

7 层责任链（对应源码 hasPermissionsToUseToolInner，顺序不可重排）：

1a DenyRule -> 1b AskRule -> 1c ToolSelfCheck -> 1d ToolDeny
-> 1e RequiresInteraction -> 1f ContentAskRule(bypass免疫) -> 1g SafetyCheck(bypass免疫)
-> 2a BypassMode -> 2b AlwaysAllow -> 3 兜底Ask

关键不变式：deny 规则、内容 ask 规则、safetyCheck（.git/.claude/.vscode）三者 bypass 免疫。

Bash 安全

6 层 defense-in-depth：AST 解析(fail-closed) -> 重定向目标验证 -> 命令注入检测 -> 危险前缀清单 -> 敏感路径检测 -> auto 模式 AI 分类器。

上下文压缩

三级压缩（对应源码 services/compact/）：

级别	触发条件	是否调模型
MicroCompactor	时间 gap >= 60min	否（纯本地 content 替换）
AutoCompactor	token >= contextWindow - 13000	是（调模型摘要）
手动 /compact	用户命令	是

Hook 系统

• 28 种事件：PreToolUse/PostToolUse/SessionStart/Stop/PermissionRequest/SubagentStart 等
• 4 类执行器：command(spawn shell) / prompt(调 LLM) / http(POST) / agent(子代理)
• SSRF 防护：http hook 拒绝内网/metadata 地址（169.254.169.254、10.x、172.16-31.x、192.168.x）
• PostSamplingHook：每轮 API 采样后触发的程序化 hook（用于记忆提取/摘要）

自动记忆系统

• memdir：~/.claude/projects/<git-root>/memory/ 维护带 frontmatter 的记忆文件（4 类：user/feedback/project/reference）
• RelevantMemorySelector：每轮用 side-query（haiku 小模型）选 <=5 个相关记忆注入
• MemoryExtractor：每轮结束用 forked agent（共享 prompt cache）提取记忆
• 路径安全：拒绝 null byte / URL 编码遍历 / UNC / Unicode 规范化攻击

Plan Mode V2

4 阶段状态机：interview(只读采访) -> propose(写计划文件) -> approved(用户批准) -> execute(执行)

allowedPrompts 预授权：{tool:"Bash", prompt:"run tests"} -> session 级 allow 规则 "Bash(prompt: run tests)"

Cron 定时任务

• 5 字段 cron 解析（分时日月周，本地时间）
• 1s 轮询 + O_EXCL 进程锁（防多实例双触发）+ 错过任务补偿
• 确定性抖动：jitterFrac(taskId) = parseInt(id前8位hex,16)/0x100000000
• 3 个工具：ScheduleCron / ScheduleCronDelete / ScheduleCronList

LSP 集成

• 基于 Eclipse LSP4J 的语言服务器客户端
• 9 个操作：hover / findReferences / goToDefinition / documentSymbol / workspaceSymbol / goToImplementation / prepareCallHierarchy / incomingCalls / outgoingCalls
• 诊断 LRU 缓存（500 文件，10/文件，30 总计）+ 去重 + 限流 + 被动注入对话

子代理

• AgentTool：派发独立子代理处理子任务（独立消息历史、受限工具集、后台执行）
• CoordinatorMode：主代理协调，Worker 受限工具集（Bash/Edit/Read/MCP）
• Task 工具：TaskList / TaskGet / TaskStop

技术栈

组件	技术
语言	Java 21（virtual threads）
框架	Spring Boot 4.1 + Spring AI 2.0.0
构建	Maven 3.9
终端 UI	JLine 3
响应式	Project Reactor
Token 计数	jtokkit
LSP	Eclipse LSP4J 0.23.1
JSON	Jackson
测试	JUnit 5 + AssertJ

测试

246 项单元测试覆盖全部核心功能与安全不变式（原 151 项 + Phase 0-7 新增 95 项）：

测试类	测试数	覆盖内容
PermissionChainTest	5	deny 优先于 allow、safetyCheck bypass 免疫
BashSafetyTest	8	危险前缀、不可逆破坏、命令注入、fail-closed
CompactingChatMemoryTest	4	阈值触发、摘要前置、forceCompact
ToolConcurrencyTest	2	并发安全工具并行、非并发安全工具串行
CleanupRegistryTest	3	注册/取消注册/幂等执行
NotebookEditToolTest	3	replace/insert/非 .ipynb 拒绝
ConfigToolTest	4	GET/SET/白名单/boolean 转换
WebSearchToolTest	4	空查询拒绝/domains 互斥/只读并发
FileHistoryTest	3	trackEdit+rewind/快照复用/diff 统计
OutputStylesLoaderTest	4	内置/用户/项目覆盖/自定义检测
ToolSearchToolTest	4	select 前缀/关键词评分/无匹配/只读
SkillToolTest	4	前导/兼容/未知拒绝/$ARGUMENTS 插值
PowerShellSafetyTest	18	16 破坏性正则/8 安全预检/cmdlet allowlist
ReplToolTest	4	REPL_ONLY_TOOLS/未知拒绝/派发执行
InternalWriteTrackerTest	3	窗口内消费/超时保留/无标记
SettingsExtensionTest	7	缓存存储/校验/权限规则过滤
ToolToMcpAdapterTest	2	Tool->MCP 转换/Specification
VimModeTest	20	11 状态转移/dd/i/a/计数乘法/motion/textObject
KeybindingsTest	14	修饰键别名/chord/escape 取消/last-match-wins
WorktreeManagerTest	12	slug 校验/分支名/findGitRoot/真实 git worktree
AutoUpdaterTest	8	版本比较/降级检测/fail-open/UpdateLock
TeammateMailboxTest	6	读写/追加/清空/类型保持
SwarmTest	9	团队创建/拒绝重复/持久化/ThreadLocal 隔离/工具执行
ContentBlockCacheControlTest	12	Phase 0.1: CacheControl record + Ask suggestions
DenialTrackingTest	9	Phase 0.3: 3连续/20总计->ask 限额修复
ExitPlanModeApprovalFlowTest	9	Phase 1: 审批流修复 + PlanApprovalOption 8选项
LspDiagnosticRegistrationTest	6	Phase 1: publishDiagnostics 转发 + 去重/限额/排序
CronTaskFieldsTest	7	Phase 2: agentId/permanent + forPersistence + 门控
McpToolsTest	10	Phase 4: 工具名规范化 + 策略过滤 + 传输类型解析
MicrocompactTest	14	Phase 5: apiMicrocompact + cachedMicrocompact + 去重/消费
MemorySubsystemTest	11	Phase 6: autoDream锁 + SessionMemory阈值 + 模板10section
PlanModeCompletionTest	9	Phase 7: interview gate + recoverPlanFromMessages
BackgroundTaskRegistryTest	8	Phase 3: register/kill/update/cleanup + sealed 4类型

mvn -pl ccc-test test

与 Claude Code 源码的对应关系

详细映射见 IMPLEMENTATION_REPORT.md。

功能亮点

• 完整的工具生态：16+ 内置工具覆盖文件操作、Shell 执行、网络搜索、Notebook 编辑、配置管理、Skill 调用、工具搜索、REPL 模式
• 6 层 Bash 安全 + PowerShell CLM 安全栈：fail-closed 设计，16 条破坏性命令正则检测
• 11 状态 Vim 状态机：纯函数式实现，支持 operator/motion/text object/dot-repeat
• 18 上下文快捷键系统：chord 前缀检测，平台感知，热重载，alt/meta 折叠
• 多 Agent 组队协作：虚拟线程 InProcess 后端，文件邮箱通信，Leader 权限桥
• 文件编辑回溯：3 阶段防竞态快照，hardlink 备份，/rewind 回溯
• MCP Server 双向：既是 MCP 客户端（连接外部工具），也作为 MCP Server 暴露自身工具
• 企业级配置：三级缓存 + WatchService 热重载 + MDM 企业托管 + 内部写追踪
• 自动更新：GitHub Releases 检查 + jar 原子替换 + OS 级文件锁

已实现功能

7 个高优先级功能 + 17 个中优先级功能 + Phase 0-7 完善已全部完成：

高优先级（7 项，已实现）

自动记忆系统 / ForkedAgent+SideQuery / LSP 集成 / Microcompact / Hook 事件补齐+SSRF / Plan Mode V2 / Cron 调度器

中优先级（17 项，已实现）

#	功能	模块	简述
1	WebSearchTool	ccc-tools	网络搜索（ChatClient + DuckDuckGo 回退）
2	SkillTool	ccc-tools	模型主动调用 skill（SPI 解耦避免循环依赖）
3	ConfigTool	ccc-tools	模型读写 settings.json（白名单+校验+持久化）
4	PowerShellTool	ccc-tools	Windows PowerShell（16 破坏性正则+8 安全预检+cmdlet allowlist）
5	NotebookEditTool	ccc-tools	Jupyter .ipynb 编辑（replace/insert/delete + Read-before-Edit）
6	REPLTool	ccc-tools	REPL 模式减少工具数/token（8 个原始工具隐藏）
7	ToolSearchTool	ccc-tools	延迟加载工具（select 前缀+关键词评分）
8	EnterWorktree/ExitWorktree	ccc-worktree	git worktree 隔离（fail-closed 变更检测）
9	fileHistory	ccc-filehistory	文件编辑前快照 + /rewind 回溯（3 阶段防竞态）
10	cleanupRegistry	ccc-core	全局清理注册表 + 幂等执行
11	autoUpdater	ccc-app/update	自动更新（GitHub Releases + jar 原子替换 + 文件锁）
12	Swarm/Teammate	ccc-swarm	多 agent 组队（虚拟线程+文件邮箱+Leader 权限桥）
13	MCP Server 入口	ccc-mcp-server	把自身工具暴露为 MCP server（stdio transport）
14	Keybindings 系统	ccc-keybindings	18 上下文 + chord 前缀检测 + 平台感知 + 热重载
15	Vim 模式	ccc-vim	11 状态有限状态机 + operator + motion + text object
16	Settings 扩展	ccc-config	三级缓存 + 校验 + WatchService 热重载 + MDM 企业托管
17	outputStyles	ccc-outputstyles	输出风格 .md 加载 + frontmatter + 注入 system prompt

Phase 0-7 完善功能（全部完成，+95 项测试）

以下功能在 Phase 0-7 中全部完成完善，对照源码补齐了所有待办细节：

功能	已完善的细节
基础架构	ClaudeCodeRequestAdvisor（Advisor 链 + system prompt + 历史 + cache_control）、AgentInvoker（替换裸 lambda）、ContentBlock.CacheControl、PermissionResult.Ask suggestions
权限系统	DenialTracking 限额修复（3/20->ask 非 deny）、PermissionCheckerImpl（桥接 Tool.checkPermissions + PermissionChain + PermissionModeStrategy）、StreamingToolExecutor 权限检查（不再绕过）、PermissionCallback 接口
记忆系统	autoDream（ConsolidationLock + 4 阶段 prompt + 门控链）、SessionMemory（10 section 模板 + 阈值触发 + forked agent）、awaySummary（haiku + 30 msg 窗口）
ForkedAgent	AgentSummary（30s 定时摘要 + deny-all canUseTool + previousSummary 跟踪）、ForkedAgentResult(text, usage) + accumulateUsage
LSP	publishDiagnostics 转发到 registry（修复丢弃 bug）、gitignore 过滤（git check-ignore 50/batch）、ContentModified 重试（-32801 + 指数退避 3 次）
Microcompact	apiMicrocompact（ContextManagementConfig + ClearToolUses/ClearThinking）、cached microcompact（CacheEditsBlock + pin/consume/markTools + 去重）
Hook	HookConfig.Event 补齐至 28 个、FileChangedWatcher（WatchService）、SessionHooks（会话级 + once 自动移除）、SkillHookRegistrar（frontmatter hooks: 解析）
Plan Mode	interview phase 门控、recoverPlanFromMessages（反向扫描）、copyPlanForResume、PlanApprovalOption 8 选项 + keep/clear-context、ExitPlanMode 不再自动批准
Cron	WatchService 文件 watch、teammate 路由（onFireTask + agentId + 孤儿清理）、门控开关、killswitch、锁接管探测
MCP	8 传输类型 + connect/reconnect/toggleEnabled、fetchToolsForServer（mcp__norm__tool）、McpPolicyFilter、McpToolNameNormalizer、headers/oauth 字段
REPL	PermissionDialog（BlockingQueue + y/n/a/e）、BackgroundTaskRegistry（sealed 4 类型 + register/kill）、ReplVimContext（生产 OperatorContext）

详见 IMPLEMENTATION_REPORT.md。

当前限制与待实现清单

本项目已实现 Claude Code 的核心架构和工具调用循环，配 API Key 后可在本地运行（读取文件、执行命令、搜索代码、编辑文件等）。但与完整的 Claude Code 相比仍有以下限制：

运行时限制（影响使用体验）

#	限制	影响	根因
1	非流式输出	工具循环完成后整块返回文本，不是逐 token 流式输出。用户在等待期间只看到 ⏳ Working... spinner，看不到实时生成的文字	Spring AI 2.0.0 的 ToolCallAdvisor.adviseStream 未实现（抛出 UnsupportedOperationException）。当前用 .call() 路径（正确处理工具循环）但无法逐 token 流式
2	权限 Ask 被拒绝	需要用户确认的工具操作（如 Bash 执行未被 allow 规则覆盖的命令）会被直接拒绝并返回错误信息，而非弹出交互式权限对话框让用户选择 y/n	ToolCallbackAdapter.PermissionChecker 对 Ask 返回拒绝消息。需要自定义 ToolCallAdvisor 子类在 doBeforeCall 中拦截并接入 PermissionDialog
3	无工具执行日志	工具执行时终端不显示"正在读取 foo.java"之类的具体工具调用进度	AgentInvoker 的 ToolProgressCallback 只有 onStart/onComplete，没有 per-tool 回调。需要 Spring AI 的工具执行事件钩子
4	非交互式 REPL	斜杠命令可用，但权限对话框、后台任务面板（Shift+Down）、Vim 模式等交互功能未接入主循环	ReplMainLoop 是最小 JLine3 线循环，PermissionDialog/BackgroundTaskRegistry/ReplVimContext 已实现但未 wire

待实现功能（按优先级）

高优先级（显著提升可用性）

#	功能	说明	预估工作量
1	流式输出 + 工具调用	实现 StreamingToolCallAdvisor（继承 ToolCallAdvisor，实现 adviseStream），让 .stream() 路径也能驱动工具循环，实现逐 token 输出	大（需实现 do/while 流式循环）
2	交互式权限对话框	自定义 ToolCallAdvisor 子类，在 doBeforeCall 中检测 Ask，阻塞等待 PermissionDialog 的用户响应（y/n/always-allow）	中（需桥接 Spring AI 工具执行循环与 REPL 输入线程）
3	工具执行进度显示	在工具执行期间显示 "📖 Reading foo.java"、"⚙ Bash: npm test" 等进度，替代通用的 ⏳ Working...	小（需 Spring AI 工具执行事件回调）

中优先级（功能完善）

#	功能	说明
4	后台任务面板	BackgroundTaskRegistry 已实现，需接入 REPL（Shift+Down 打开面板，显示/kill 后台任务）
5	Vim 模式接入	ReplVimContext 已实现，需替换 LineReader.readLine 为 VimInputHandler，在 CCJ_VIM_MODE=1 时启用
6	推测执行（Speculation）	ccc-prompt-suggestion 模块待创建；overlay 文件系统 + canUseTool 路径改写 + 消息注入
7	auto 模式 LLM 分类器	当前 RuleBasedYoloClassifier 用规则模拟；需替换为真实 LLM 两阶段 XML 分类器（stage1 快判 + stage2 thinking 复核）
8	cache_edits 请求体注入	CachedMicrocompact 已实现状态管理，但 ClaudeCodeRequestAdvisor 尚未将 cache_edits 块插入请求体的最后一条 user 消息

低优先级（锦上添花）

#	功能	说明
9	buddy（虚拟宠物）	纯趣味功能
10	voice（语音模式）	STT 流式，强依赖 claude.ai OAuth
11	migrations（设置迁移）	模型别名 fennec->opus、设置项迁移
12	claudeDesktop/Chrome 集成	桌面/Chrome 集成
13	preventSleep	macOS 防睡眠（caffeinate）
14	heapDump/doctor	堆转储诊断
15	Computer Use	macOS GUI 操控
16	Teleport/Remote	claude.ai 远程会话
17	Bridge/RemoteControl	远程控制本机
18	遥测	Datadog + OpenTelemetry + GrowthBook

详见 IMPLEMENTATION_REPORT.md。

许可

MIT License - Copyright (c) 2026 Jie Shen

本项目为学习研究用途，基于 Claude Code 的公开逆向分析报告实现，不包含 Anthropic 的专有源码。