# claude-code-java

**Repository Path**: HSKS/claude-code-java

## Basic Information

- **Project Name**: claude-code-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Java

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Java](https://img.shields.io/badge/Java-25-preview-orange.svg)](https://openjdk.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.0--M2-green.svg)](https://spring.io/)
[![LangChain4j](https://img.shields.io/badge/LangChain4j-1.13.1-purple.svg)](https://langchain4j.dev/)

> **Claude Code 的 Java + LangChain4j 重写实现** — 一个具备工业级架构设计的 AI 编程助手 CLI。

---

## 核心架构亮点

### 1. 流式响应 + 异步工具并行执行

**边收流边执行** — 这是 Claude Code 最核心的创新设计：

```
AI 流式输出 Token ─────────────────────────────────────────►
                    │
                    ▼ 检测到 tool_use 块开始
        ┌───────────────────────────┐
        │  ToolCallAccumulator      │  ← 累积 JSON 参数
        │  检测 JSON 完整性         │
        └───────────────────────────┘
                    │ 参数完整立即触发
                    ▼
        ┌───────────────────────────┐
        │  StreamingToolExecutor    │  ← 并行执行（maxConcurrency=10）
        │  ┌─────┐ ┌─────┐ ┌─────┐ │
        │  │Tool1│ │Tool2│ │Tool3│ │  ← 同时执行多个工具
        │  └─────┘ └─────┘ └─────┘ │
        └───────────────────────────┘
                    │
                    ▼ 工具结果返回
        继续接收 AI 流 ────────────────────────────────────►
```

**核心组件**：

| 组件 | 职责 |
|------|------|
| `ToolCallAccumulator` | 流式累积工具参数 JSON，完整性检测后立即触发执行 |
| `StreamingToolExecutor` | 并行执行器，最大并发 10，智能队列调度 |
| `StreamingChatResponseHandler` | 回调处理：onPartialResponse + onPartialToolCall |

**优势**：
- 无需等待完整响应，首个工具参数完整即执行
- 多工具并行，显著减少任务耗时
- 流式输出实时显示，用户感知延迟更低

---

### 2. 七步权限评估链

**分层权限控制** — 确保安全操作，灵活配置：

```
工具调用请求
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  1. BYPASS 检查                                              │
│     → 特殊场景（如 Plan 模式预览）直接跳过                    │
├─────────────────────────────────────────────────────────────┤
│  2. PLAN 模式检查                                            │
│     → 规划模式下限制写入/执行操作                            │
├─────────────────────────────────────────────────────────────┤
│  3. alwaysDeny 规则                                          │
│     → 用户配置的明确拒绝列表                                 │
├─────────────────────────────────────────────────────────────┤
│  4. alwaysAllow 规则                                         │
│     → 用户配置的明确允许列表                                 │
├─────────────────────────────────────────────────────────────┤
│  5. readOnly 工具自动判断                                    │
│     → 继承 AbstractReadOnlyTool 自动标记并发安全             │
├─────────────────────────────────────────────────────────────┤
│  6. 模式行为判断                                             │
│     → 根据 autoAccept/plan 等模式调整                       │
├─────────────────────────────────────────────────────────────┤
│  7. DangerousPatterns 检测                                   │
│     → rm -rf、force push 等危险命令模式匹配                  │
├─────────────────────────────────────────────────────────────┤
│  8. 默认 ASK                                                 │
│     → UI 弹窗请求用户确认                                    │
└─────────────────────────────────────────────────────────────┘
    │
    ▼ ALLOW / DENY / ASK
```

**配置示例** (`~/.claude/settings.json`)：

```json
{
  "permissions": {
    "allow": ["Bash(git *)", "Read(*)"],
    "deny": ["Bash(rm -rf*)", "Bash(*--force*)"]
  }
}
```

---

### 3. 三层上下文压缩策略

**智能 Token 管理** — 避免超出模型上下文限制：

| 阈值 | 触发条件 | 压缩策略 | 说明 |
|------|----------|----------|------|
| **93%** | Token 使用率达标 | **MicroCompact** | 本地截断：保留最近 6 条 tool result，>10min 的仅保留 2 条 |
| **82%** | MicroCompact 后仍超限 | **SessionMemoryCompact** | AI 摘要：保留 10K-40K token 近期段，不拆分 tool 对 |
| **98%** | 二次压缩后仍超限 | **FullCompact** | 兜底方案：API Round 分组 + PTL gap 解析 + 熔断器 |

**`TokenTracker` 实时监控**：

```java
// 三级阈值检测
if (usageRatio >= 0.98) triggerFullCompact();    // 熔断
else if (usageRatio >= 0.82) triggerSessionMemoryCompact();
else if (usageRatio >= 0.93) triggerMicroCompact();
```

---

### 4. Hook 系统

**生命周期钩子** — 在关键节点注入自定义逻辑：

| Hook | 触发时机 | 用途 |
|------|----------|------|
| `PreToolUse` | 工具执行前 | 权限拦截、参数校验、日志记录 |
| `PostToolUse` | 工具执行后 | 结果处理、通知发送、审计日志 |
| `Notification` | 通知事件 | 自定义通知处理 |
| `Stop` | 会话结束 | 清理资源、保存状态 |

**配置示例**：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["echo 'Executing: $TOOL_INPUT'"]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": ["git add $TOOL_INPUT_PATH"]
      }
    ]
  }
}
```

**`HookManager` 执行流程**：

```
工具调用请求 → PreToolUse Hook 执行 → 权限评估 → 工具执行 → PostToolUse Hook 执行 → 返回结果
```

---

### 5. Skills 技能系统

**可扩展技能模块** — 封装复杂任务为可复用单元：

**三级加载路径**：

```
~/.claude/skills/          ← 全局技能（所有项目可用）
项目/.claude/skills/       ← 项目技能（当前项目专用）
命令行 --skill 参数        ← 临时加载
```

**Skill 结构** (`SKILL.md`)：

```markdown
---
name: my-skill
description: 自定义技能描述
trigger: /my-skill    ← 斜杠命令触发
---

# 技能实现指令

当用户输入 /my-skill 时，执行以下操作...
```

**内置 Skills 示例**：

| Skill | 说明 |
|-------|------|
| `init` | 初始化项目 CLAUDE.md |
| `review` | PR 代码审查 |
| `security-review` | 安全漏洞审查 |
| `graphify` | 输入转换为知识图谱 |
| `claude-api` | Claude API 应用开发助手 |

---

### 6. MCP (Model Context Protocol)

**外部工具协议** — 连接外部工具服务器扩展能力：

**传输方式**：

| 传输 | 适用场景 | 实现 |
|------|----------|------|
| **StdIO** | 本地进程通信 | `StdioTransport` |
| **HTTP-SSE** | 远程服务器 | `HttpSseTransport` |

**配置示例** (`~/.claude/mcp.json`)：

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "transport": "stdio"
    },
    "github": {
      "url": "https://mcp.github.com/sse",
      "transport": "http-sse"
    }
  }
}
```

**MCP 工具桥接**：

```
MCP Server 工具 ──► McpManager 注册 ──► McpToolBridge 包装 ──► ToolRegistry 可调用
```

---

### 7. 工具并行控制

**智能并发调度** — `StreamingToolExecutor` 实现：

```java
// 并发控制参数
maxConcurrency = 10;           // 最大并行数
queueCapacity = 100;           // 队列容量

// 并发安全标记
interface Tool {
    boolean isConcurrencySafe();  // 工具声明是否可并行执行
}

// AbstractReadOnlyTool 自动标记
abstract class AbstractReadOnlyTool implements Tool {
    @Override
    public boolean isConcurrencySafe() { return true; }
}
```

**执行逻辑**：

1. 工具参数完整 → 加入执行队列
2. 队列调度 → 当前活跃数 < maxConcurrency 时启动
3. 并发安全工具 → 直接并行执行
4. 非安全工具 → 串行等待
5. 结果聚合 → 返回 AgentLoop

---

### 8. LSP 语言服务器集成

**代码智能支持** — 多语言诊断与导航：

| 功能 | LSP 方法 | 说明 |
|------|----------|------|
| 跳转定义 | `goToDefinition` | 定位符号定义位置 |
| 查找引用 | `findReferences` | 全项目引用搜索 |
| Hover 信息 | `hover` | 类型、文档信息 |
| 文档符号 | `documentSymbol` | 当前文件符号列表 |
| 工作区符号 | `workspaceSymbol` | 全项目符号搜索 |
| 诊断 | `diagnostics` | 实时错误/警告检测 |

**支持语言**（通过配置扩展）：

- Java、TypeScript、JavaScript、Python、Go、Rust 等

---

## 核心流程全景图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              用户输入                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  命令检测                                         │
│  └─ 检测 /xxx 前缀 → CommandRegistry 查找 → 执行命令                          │
│  └─ 普通输入 → 进入 AgentLoop                                                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  SystemPromptBuilder 构建请求                                                │
│  └─ CLAUDE.md 加载（项目级 + 全局级）                                         │
│  └─ Skills 技能注入                                                          │
│  └─ Git 上下文（分支、状态、最近提交）                                        │
│  └─ MCP 工具列表                                                             │
│  └─ LSP 诊断信息                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  StreamingChatModel.chat(request, StreamingChatResponseHandler)             │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  onPartialResponse(token)    → 实时输出到终端                        │   │
│  │  onPartialThinking(thinking) → Thinking 显示                         │   │
│  │  onPartialToolCall           → ToolCallAccumulator 累积              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼ 参数完整检测
┌─────────────────────────────────────────────────────────────────────────────┐
│  StreamingToolExecutor 并行执行                                              │
│                                                                              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                        │
│  │ Tool 1  │  │ Tool 2  │  │ Tool 3  │  │ Tool 4  │  ← 并行执行            │
│  │(safe)   │  │(safe)   │  │(safe)   │  │(unsafe) │                        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                        │
│       │            │            │            │                              │
│       ▼            ▼            ▼            ▼                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  HookManager                                                         │   │
│  │  ├─ PreToolUse Hook 执行                                             │   │
│  │  ├─ PermissionRuleEngine 权限评估                                    │   │
│  │  │   → BYPASS → PLAN → alwaysDeny → alwaysAllow                     │   │
│  │  │   → readOnly → 模式 → DangerousPatterns → ASK                    │   │
│  │  ├─ 工具实际执行                                                     │   │
│  │  └─ PostToolUse Hook 执行                                            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼ 工具结果返回
┌─────────────────────────────────────────────────────────────────────────────┐
│  TokenTracker 监控                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  使用率 ≥ 93% → MicroCompact     （本地截断）                        │   │
│  │  使用率 ≥ 82% → SessionMemoryCompact （AI 摘要）                     │   │
│  │  使用率 ≥ 98% → FullCompact      （兜底压缩）                        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼ 继续循环或结束
┌─────────────────────────────────────────────────────────────────────────────┐
│  SessionMemoryService 持久化                                                 │
│  └─ 跨会话记忆保存                                                           │
│  └ ConversationPersistence 对话保存                                          │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| **JDK** | 25 | preview 特性：pattern matching、string templates |
| **Spring Boot** | 4.1.0-M2 | 应用框架、依赖注入 |
| **LangChain4j** | 1.13.1 | AI 模型调用、流式 API |
| **Jink** | 0.5.0 | React-like 终端 UI 框架 |
| **JLine** | 3.28.0 | 终端交互（FFM 原生支持） |
| **Picocli** | 4.7.6 | CLI 参数解析 |

---

## 双 API 提供者

通过 `CLAUDE_CODE_PROVIDER` 环境变量切换：

| 提供者 | 模块 | 特性 |
|--------|------|------|
| `openai` | langchain4j-open-ai | 兼容 OpenAI 格式（DeepSeek、Azure 等） |
| `anthropic` | langchain4j-anthropic | 原生 API，支持 **extended thinking** |

---

## 快速开始

详见 [BUILD.md](BUILD.md)。

**开发模式**：

```bash
export JAVA_HOME=/path/to/jdk-25
export AI_API_KEY=your-api-key
mvn spring-boot:run
```

**发行版构建**：

```bash
# Windows
.\packaging\build-dist.ps1 -JavaHome "C:\Dev\jdk-25.0.2"

# Linux/macOS
JAVA_HOME=/path/to/jdk-25 ./packaging/build-dist.sh
```

---

## 环境变量

| 变量 | 必须 | 说明 |
|------|------|------|
| `AI_API_KEY` | ✅ | API 密钥 |
| `CLAUDE_CODE_PROVIDER` | ❌ | `openai` / `anthropic` |
| `AI_BASE_URL` | ❌ | 自定义 API 地址 |
| `AI_MODEL` | ❌ | 模型名称 |
| `AI_MAX_TOKENS` | ❌ | 最大生成 Token |
| `CLAUDE_CODE_CONTEXT_WINDOW` | ❌ | 上下文窗口大小 |

---

## 项目结构

```
src/main/java/com/claudecode/
├── core/
│   ├── AgentLoop.java              ← 核心 Agent 循环
│   ├── StreamingToolExecutor.java  ← 流式工具并行执行器
│   ├── ToolCallAccumulator.java    ← 工具参数累积器
│   ├── TokenTracker.java           ← Token 监控
│   ├── HookManager.java            ← Hook 生命周期管理
│   ├── SessionMemoryService.java   ← 跨会话记忆
│   └── compact/                    ← 三层压缩实现
├── tool/
│   ├── Tool.java                   ← 工具接口（含 isConcurrencySafe）
│   ├── AbstractReadOnlyTool.java   ← 只读工具基类
│   ├── ToolRegistry.java           ← 工具注册中心
│   └── impl/                       ← 34 个工具实现
├── command/
│   ├── SlashCommand.java           ← 命令接口
│   ├── CommandRegistry.java        ← 命令注册中心
│   └── impl/                       ← 54 个命令实现
├── permission/
│   ├── PermissionRuleEngine.java   ← 7 步权限评估链
│   ├── DangerousPatterns.java      ← 危险命令模式匹配
│   └ PermissionSettings.java       ← 权限配置加载
├── context/
│   ├── SystemPromptBuilder.java    ← 系统提示词构建
│   ├── SkillLoader.java            ← Skills 加载
│   ├── AgentLoader.java            ← Agent 配置解析
│   └ ClaudeMdLoader.java           ← CLAUDE.md 加载
├── mcp/
│   ├── McpManager.java             ← MCP 协议管理
│   ├── McpToolBridge.java          ← MCP 工具桥接
│   ├── StdioTransport.java         ← StdIO 传输
│   └ HttpSseTransport.java         ← HTTP-SSE 传输
├── lsp/
│   └ LSPServerManager.java         ← LSP 服务器生命周期
├── tui/
│   ├── JinkReplSession.java        ← Jink 全屏 TUI
│   └ ClaudeCodeComponent.java      ← 主界面组件
└── config/
    └ LangChain4jConfig.java        ← 模型 Bean 配置
```

---

## 许可证

[Apache License 2.0](LICENSE)

Copyright 2025 hsk