claude-code/需求文档.md

# Claude Code Java 重写

## 1. 需求背景

Claude Code 是 Anthropic 开发的一款基于 Claude AI 的 CLI 编码助手工具。原版使用 TypeScript + Ink（React终端框架）实现，源码规模约 **2,289 个文件**，分布在 **38 个模块**中，提供了丰富的终端交互体验，包括工具调用、斜杠命令、CLAUDE.md 记忆加载、Skills 技能系统等功能。

本项目的目标是使用 **Java + Spring AI** 对 Claude Code 的核心功能进行重写，实现一个功能完整、交互体验良好的 CLI AI 编码助手。参考 `claude-code-learn` 项目中的 Spring AI 实践模式（AgentLoop 显式循环、AgentTool 工具协议等），但在 CLI 交互体验上需要做到更加完善。

### 业务目标
- 深入理解 Claude Code 的架构设计和核心原理
- 使用 Java 生态（Spring AI + JLine + Picocli）实现等价功能
- 提供可扩展的工具和命令系统
- 支持完整的终端交互体验（banner、输入框、thinking 显示、工具状态等）

## 2. 功能描述

### 2.1 核心 REPL 循环

**对应源码**: `claude-code/src/screens/REPL.tsx`, `claude-code/src/query.ts`
**Java 设计**: `AgentLoop.java`, `ReplSession.java`

用户输入 → 斜杠命令检测 → AI 调用 → 工具调用循环 → 结果输出 → 等待下一轮输入

关键要求：
- 使用 `ChatModel`（而非 `ChatClient.call()`）自定义 REPL 循环
- `ChatClient.call()` 内置了工具循环但不够灵活，无法在每轮工具调用之间插入自定义逻辑（如权限检查、状态显示、进度更新）
- 显式控制每一轮：构建 Prompt → 调用模型 → 检测工具调用 → 执行工具 → 收集结果 → 继续或结束
- 支持最大迭代限制（防止无限循环，默认 50 轮）
- 消息历史管理（UserMessage → AssistantMessage → ToolResponseMessage 循环）

### 2.2 工具系统

**对应源码**: `claude-code/src/Tool.ts`, `claude-code/src/tools.ts`, `claude-code/src/tools/*`
**Java 设计**: `Tool.java` 接口, `ToolRegistry.java`, `tools/impl/*`

工具协议接口定义：
```
Tool {
  name()          - 唯一标识
  description()   - 给 LLM 的描述
  inputSchema()   - JSON Schema 参数定义
  execute()       - 执行逻辑
  checkPermission() - 权限前置检查
  isEnabled()     - 是否启用
  isReadOnly()    - 是否只读
  activityDescription() - 人类可读的进度描述
}
```

第一期实现的工具集（核心工具）：

| 工具名 | 功能 | 对应源码 |
|-------|------|---------|
| BashTool | 执行 Shell/Cmd 命令 | tools/BashTool/ |
| FileReadTool | 读取文件内容 | tools/FileReadTool/ |
| FileWriteTool | 写入文件 | tools/FileWriteTool/ |
| FileEditTool | 查找替换编辑 | tools/FileEditTool/ |
| GlobTool | 文件名通配搜索 | tools/GlobTool/ |
| GrepTool | 文件内容正则搜索 | tools/GrepTool/ |
| WebFetchTool | 获取 URL 内容 | tools/WebFetchTool/ |
| TodoWriteTool | 管理待办事项 | tools/TodoWriteTool/ |

### 2.3 斜杠命令系统

**对应源码**: `claude-code/src/commands.ts`, `claude-code/src/commands/*`
**Java 设计**: `SlashCommand.java` 接口, `CommandRegistry.java`, `commands/impl/*`

命令接口定义：
```
SlashCommand {
  name()         - 命令名称（不含 /）
  aliases()      - 别名列表
  description()  - 命令描述
  execute()      - 执行逻辑
  isEnabled()    - 是否启用
}
```

第一期实现的命令集：

| 命令 | 功能 | 对应源码 |
|------|------|---------|
| /help | 显示帮助信息 | commands/help/ |
| /clear | 清除对话历史 | commands/clear/ |
| /compact | 压缩上下文 | commands/compact/ |
| /exit | 退出应用 | commands/exit/ |
| /cost | 显示 Token 消耗 | commands/cost/ |
| /model | 切换模型 | commands/model/ |
| /memory | 管理 CLAUDE.md | commands/memory/ |
| /context | 显示当前上下文 | commands/context/ |

### 2.4 上下文与系统提示词构建

**对应源码**: `claude-code/src/context.ts`, `claude-code/src/constants/prompts.ts`, `claude-code/src/utils/claudemd.ts`
**Java 设计**: `ContextBuilder.java`, `SystemPromptBuilder.java`, `ClaudeMdLoader.java`

系统提示词组成结构：
```
1. 基础系统提示（角色定义、行为规则）
2. 工具使用指导（每个工具的使用建议）
3. 用户上下文
   ├── CLAUDE.md 内容（项目级 + 用户级 + 管理级）
   ├── 当前日期时间
   └── 自定义指令
4. 系统上下文
   ├── Git 状态（分支、最近提交、变更文件）
   ├── 操作系统信息
   └── 工作目录
5. 技能列表（可用 skills）
```

CLAUDE.md 加载优先级（从低到高）：
1. 管理级: `/etc/claude-code/CLAUDE.md`（Linux）或等价位置
2. 用户级: `~/.claude/CLAUDE.md`
3. 项目级: `./CLAUDE.md` 或 `./.claude/CLAUDE.md`
4. 本地级: `./CLAUDE.local.md`

### 2.5 Skills 技能系统

**对应源码**: `claude-code/src/skills/`, `claude-code/src/skills/bundledSkills.ts`
**Java 设计**: `SkillLoader.java`, `skills/` 资源目录

技能定义格式（Markdown + YAML Frontmatter）：
```yaml
---
name: "技能名称"
description: "技能描述"
allowed-tools: [BashTool, FileReadTool]
---
技能的具体指令内容（Markdown 格式）
```

技能加载位置：
1. 用户全局: `~/.claude/skills/`
2. 项目级: `.claude/skills/`
3. 内置: 应用内预打包

### 2.6 终端 UI 交互

**对应源码**: `claude-code/src/components/`, `claude-code/src/ink/`
**Java 设计**: `console/` 包（使用 JLine 3 实现）

#### Banner 显示
启动时显示 ASCII Art Logo + 版本信息 + 模型信息 + 工作目录

#### 输入提示符
- 支持多行输入（Shift+Enter 换行）
- 输入历史（上下箭头浏览）
- 命令补全（Tab 键）
- 支持斜杠命令自动补全

#### Thinking 显示
- AI 思考过程实时显示
- 可折叠/展开
- 使用 `∴ Thinking...` 前缀标记

#### 工具调用状态
- 工具执行中显示 Spinner 动画
- 显示工具名称和参数摘要
- 完成后显示 ● 成功/● 失败状态
- 支持实时进度更新

#### Markdown 渲染
- 代码块语法高亮
- 标题、列表、链接格式化
- 终端宽度自适应

### 2.7 流式输出

**对应源码**: `claude-code/src/services/api/`, `claude-code/src/query.ts`
**Java 设计**: `StreamingAgentLoop.java`, `StreamingHandler.java`

- 使用 Spring AI 的 `ChatModel.stream()` 方法
- 返回 `Flux<ChatResponse>` 流式响应
- 实时渲染 AI 回复文本
- 实时处理工具调用参数（partial JSON）

### 2.8 配置管理

**对应源码**: `claude-code/src/commands/config/`
**Java 设计**: `application.yml` + `AppConfig.java`

配置项：
- API Key（环境变量或配置文件）
- Base URL（支持自定义 API 端点）
- 模型名称（默认 claude-sonnet-4-20250514）
- 最大 Token 数
- 工作目录
- 主题（暗色/亮色）

## 3. 技术实现建议

### 3.1 技术栈选型

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| 运行时 | JDK 25 | 最新 JDK，支持虚拟线程 |
| 框架 | Spring Boot 3.5.x | 基础框架 |
| AI | Spring AI 2.0.0-M4 | AI 模型调用 |
| CLI 解析 | Picocli 4.7+ | 命令行参数解析 |
| 终端交互 | JLine 3.28+ | 行编辑、历史、补全 |
| HTTP | Spring WebFlux | 流式输出（Reactor） |
| 构建 | Maven | 项目构建 |

### 3.2 架构设计

```
┌─────────────────────────────────────────────┐
│  CLI 层 (Picocli)                           │
│  ClaudeCodeCommand → 解析参数 → 启动应用     │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  REPL 层 (JLine 3)                          │
│  ReplSession → 用户输入 → 命令分发           │
│  ├── 斜杠命令 → CommandRegistry → 直接执行   │
│  └── 对话内容 → AgentLoop → AI 调用          │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  Agent 循环层 (Spring AI ChatModel)          │
│  AgentLoop.run(input)                        │
│  ├── 构建 Prompt (System + History + User)   │
│  ├── 调用 ChatModel.call/stream()            │
│  ├── 检测工具调用 → ToolRegistry.execute()   │
│  ├── 收集结果 → 消息历史追加                  │
│  └── 循环直到无工具调用                       │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  工具层                                      │
│  ToolRegistry                                │
│  ├── BashTool, FileReadTool, ...             │
│  ├── 权限检查                                │
│  └── 结果格式化                              │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  渲染层 (ConsoleRenderer)                    │
│  ├── BannerPrinter (启动横幅)                │
│  ├── ThinkingRenderer (思考过程)             │
│  ├── ToolStatusRenderer (工具状态)           │
│  ├── MarkdownRenderer (Markdown渲染)         │
│  └── SpinnerAnimation (加载动画)             │
└─────────────────────────────────────────────┘
```

### 3.3 关键设计决策

1. **ChatModel vs ChatClient**: 使用 ChatModel 自定义循环
   - ChatClient.call() 封装了完整的工具循环，但无法在中间插入自定义逻辑
   - ChatModel.call() 返回原始响应，可以自行控制工具调用流程
   - 参考 claude-code-learn 的 AgentLoop 实现模式

2. **工具注册方式**: 双模式支持
   - `Tool` 接口（协议模式，适合复杂工具）
   - `@Tool` 注解（简单模式，适合简单工具）
   - `ToolCallback` 适配器桥接两种模式

3. **消息历史**: 自行管理 `List<Message>`
   - 不依赖 Spring AI 的 ChatMemory
   - 精确控制消息格式和截断

4. **终端 UI**: JLine 3 + ANSI 转义码
   - 不使用 React 渲染模型（原版 Ink 方式）
   - 直接操作终端输出流
   - 支持 Windows Terminal / PowerShell

## 4. 验收标准

### 4.1 基础功能
- [x] 应用可正常启动并显示 Banner
- [x] 支持通过环境变量或配置文件设置 API Key 和模型
- [x] REPL 循环正常工作：输入问题 → 获得 AI 回复
- [x] 工具调用循环正常：AI 可以调用工具并获取结果
- [x] 至少支持 8 个核心工具（实际 11 个）
- [x] 至少支持 8 个斜杠命令（实际 11 个）

### 4.2 交互体验
- [x] Banner 显示正常（Logo + 版本 + 模型信息 + Provider + URL）
- [x] 输入提示符支持行编辑和历史记录
- [x] Thinking 过程可见（Spinner 动画 + "Thinking..." 提示）
- [x] 工具调用时显示 Spinner 动画和状态
- [x] 支持 ANSI 颜色输出
- [x] Markdown 内容基本格式化

### 4.3 上下文功能
- [x] 能加载项目 CLAUDE.md
- [x] 能加载用户级 CLAUDE.md
- [x] Git 上下文信息正确收集
- [x] 系统提示词包含所有必要信息

### 4.4 代码质量
- [x] Maven 编译无错误
- [x] 代码结构清晰，包划分合理
- [x] 关键逻辑有中文注释
- [x] 提供完整的使用文档（README.md）

### 4.5 已超出原始验收标准的功能
- [x] 流式输出（Flux<ChatResponse> 逐 token 实时显示）
- [x] 对话历史持久化（JSON 格式自动保存/加载）
- [x] AI 驱动的上下文压缩（/compact 生成摘要）
- [x] 多行输入支持（反斜杠续行）
- [x] 双 API 提供者（OpenAI + Anthropic 切换）
- [x] /history 命令查看保存的对话

---

## 5. 实现状态总结

### 5.1 已实现功能清单

| 类别 | 功能 | 状态 |
|------|------|------|
| **REPL 核心** | ChatModel 自定义循环 | ✅ |
| | 流式输出 (Flux) | ✅ |
| | 阻塞模式降级 | ✅ |
| | 最大迭代限制 (50轮) | ✅ |
| | 消息历史管理 | ✅ |
| | 对话持久化 | ✅ |
| **工具系统 (18个)** | BashTool | ✅ |
| | FileReadTool | ✅ |
| | FileWriteTool | ✅ |
| | FileEditTool | ✅ |
| | GlobTool | ✅ |
| | GrepTool | ✅ |
| | WebFetchTool | ✅ |
| | TodoWriteTool | ✅ |
| | ListFilesTool | ✅ |
| | AgentTool | ✅ |
| | NotebookEditTool | ✅ |
| | WebSearchTool (P0) | ✅ |
| | AskUserQuestionTool (P0) | ✅ |
| | TaskCreate/Get/List/Update (P2) | ✅ |
| | ConfigTool (P2) | ✅ |
| | McpToolBridge (P2) | ✅ |
| **命令系统 (28个)** | 基础: /help, /clear, /exit 等 11个 | ✅ |
| | P0: /diff, /version, /skills, /memory, /copy | ✅ |
| | P1: /resume, /export, /commit | ✅ |
| | P2: /hooks, /review, /stats, /branch, /rewind, /tag | ✅ |
| | P2: /security-review, /mcp, /plugin | ✅ |
| **上下文** | CLAUDE.md 加载 | ✅ |
| | Skills 技能加载 | ✅ |
| | Git 上下文收集 | ✅ |
| | 系统提示词构建 | ✅ |
| **终端 UI** | Banner + Provider 信息 | ✅ |
| | JLine 行编辑/历史/Tab补全 | ✅ |
| | 多行输入 | ✅ |
| | Spinner 动画 | ✅ |
| | 工具状态渲染 | ✅ |
| | ANSI 颜色 | ✅ |
| | Markdown 渲染 | ✅ |
| | 代码语法高亮 (P1) | ✅ |
| | 底部状态行 (P1) | ✅ |
| | DiffRenderer 彩色diff (P2) | ✅ |
| **配置** | 双 API 提供者切换 | ✅ |
| | 环境变量统一 | ✅ |
| | Token/费用追踪 | ✅ |
| **P0 核心增强** | 权限确认机制 | ✅ |
| | Thinking 内容显示 | ✅ |
| **P1 体验增强** | Hook 系统 (4种钩子) | ✅ |
| | Vim 模式输入 | ✅ |
| **P2 扩展** | MCP 客户端 (JSON-RPC/StdIO) | ✅ |
| | MCP 多服务器管理 | ✅ |
| | 插件系统 (JAR加载) | ✅ |
| | 任务管理系统 | ✅ |
| | 对话分支/标签/回退 | ✅ |
| | GrepTool | ✅ |
| | WebFetchTool | ✅ |
| | TodoWriteTool | ✅ |
| | ListFilesTool | ✅ |
| | AgentTool | ✅ |
| | NotebookEditTool | ✅ |
| **命令系统 (11个)** | /help, /clear, /exit | ✅ |
| | /compact (AI摘要) | ✅ |
| | /cost, /model, /status | ✅ |
| | /context, /config, /init | ✅ |
| | /history | ✅ |
| **上下文** | CLAUDE.md 加载 | ✅ |
| | Skills 技能加载 | ✅ |
| | Git 上下文收集 | ✅ |
| | 系统提示词构建 | ✅ |
| **终端 UI** | Banner + Provider 信息 | ✅ |
| | JLine 行编辑/历史/Tab补全 | ✅ |
| | 多行输入 | ✅ |
| | Spinner 动画 | ✅ |
| | 工具状态渲染 | ✅ |
| | ANSI 颜色 | ✅ |
| | Markdown 渲染 | ✅ |
| **配置** | 双 API 提供者切换 | ✅ |
| | 环境变量统一 | ✅ |
| | Token/费用追踪 | ✅ |

### 5.2 未实现功能清单

> ⚠️ P0、P1、P2 已全部实现。以下仅列出 P3（跳过）项目。

#### 🔴 P0 核心 — ✅ 已全部实现

#### 🟡 P1 重要 — ✅ 已全部实现

#### 🟢 P2 扩展 — ✅ 已全部实现

#### ⚪ P3 跳过（不适用于 Java CLI）

| 功能 | 原因 |
|------|------|
| Ink/React UI 框架 | Java 用 JLine 替代 |
| IDE 桥接 (bridge/) | 需要独立的 IDE 插件 |
| 语音功能 (voice/) | 平台特定 |
| 远程会话 (remote/) | 需要服务端 |
| 沙箱隔离 (sandbox/) | 需要容器化 |
| 遥测 (telemetry/) | 非核心功能 |

---

## 附录 A：claude-code 源码全模块覆盖清单

### A.1 模块规模统计

| 模块 | 文件数 | 说明 |
|------|--------|------|
| utils/ | 564 | 工具函数库（权限、Shell、Git、文件、插件、配置等） |
| components/ | 389 | React UI 组件（消息、输入、设计系统、差异视图等） |
| commands/ | 207 | 斜杠命令集合（79+ 命令） |
| tools/ | 184 | AI 工具系统（40 个工具） |
| services/ | 130 | 业务服务层（API、MCP、OAuth、压缩、分析等） |
| hooks/ | 104 | React Hooks（UI交互、会话、权限、通知等） |
| ink/ | 96 | 自定义 Ink 终端 UI 框架 |
| bridge/ | 31 | IDE/编辑器集成桥接层 |
| constants/ | 21 | 全局常量（提示词、限制、错误码等） |
| skills/ | 20 | 技能管理系统（17 个内置技能） |
| cli/ | 19 | CLI 输出处理和传输层 |
| keybindings/ | 14 | 快捷键绑定系统 |
| tasks/ | 12 | 后台任务执行系统 |
| types/ | 11 | TypeScript 类型定义 |
| migrations/ | 11 | 数据迁移脚本 |
| context/ | 9 | React Context（状态、通知、邮箱等） |
| memdir/ | 8 | 记忆库/记忆系统 |
| entrypoints/ | 8 | 应用入口点（CLI、MCP、SDK） |
| buddy/ | 6 | 伙伴/助手角色系统 |
| state/ | 6 | 全局状态管理 |
| vim/ | 5 | Vim 编辑模式 |
| native-ts/ | 4 | 原生扩展（C++ 绑定） |
| query/ | 4 | 查询系统（Token预算等） |
| remote/ | 4 | 远程连接管理 |
| screens/ | 3 | 屏幕组件（REPL、Doctor、Resume） |
| server/ | 3 | 直连服务器 |
| upstreamproxy/ | 2 | 代理和中继 |
| plugins/ | 2 | 插件系统 |
| 顶层文件 | 18 | main.tsx、context.ts、Tool.ts 等核心入口 |
| 其他(4个) | 4 | coordinator/、schemas/、outputStyles/、voice/ 等 |
| **总计** | **~2,289** | |

### A.2 模块覆盖级别划分

每个模块按 Java 重写的优先级分为四个级别：

- 🔴 **P0 核心（Must）**: 不实现则系统无法运行
- 🟡 **P1 重要（Should）**: 影响核心用户体验
- 🟢 **P2 扩展（Could）**: 增强功能，可后续迭代
- ⚪ **P3 跳过（Skip）**: 平台特定或不适用于 Java 版本

---

### A.3 顶层入口文件（18 个文件）

| 文件 | 级别 | Java 对应 | 说明 |
|------|------|----------|------|
| main.tsx | 🔴 P0 | ClaudeCodeRunner | 应用启动编排（初始化上下文、加载工具、启动REPL） |
| context.ts | 🔴 P0 | ContextBuilder | 收集系统和用户上下文（Git状态、CLAUDE.md、日期） |
| Tool.ts | 🔴 P0 | Tool.java 接口 | 工具协议定义（name、description、inputSchema、call等） |
| tools.ts | 🔴 P0 | ToolRegistry | 工具集合注册和加载 |
| commands.ts | 🔴 P0 | CommandRegistry | 斜杠命令集合注册 |
| Task.ts | 🟡 P1 | TaskDefinition | 任务类定义 |
| tasks.ts | 🟡 P1 | TaskManager | 任务管理 |
| query.ts | 🔴 P0 | AgentLoop.query() | AI 查询入口（消息构建、API调用、流式处理） |
| QueryEngine.ts | 🔴 P0 | AgentLoop | 查询执行引擎（工具循环） |
| setup.ts | 🔴 P0 | AppConfig | 初始化和配置 |
| history.ts | 🟡 P1 | SessionHistory | 对话历史持久化 |
| ink.ts | 🔴 P0 | ConsoleRenderer | 终端渲染入口（Java 用 JLine 替代） |
| replLauncher.tsx | 🔴 P0 | ReplSession | REPL 启动器 |
| cost-tracker.ts | 🟡 P1 | CostTracker | Token/费用追踪 |
| costHook.ts | 🟡 P1 | (集成到CostTracker) | 费用钩子 |
| dialogLaunchers.tsx | 🟢 P2 | - | 对话框启动器（React特定） |
| interactiveHelpers.tsx | 🟡 P1 | InputHandler | 交互式辅助 |
| projectOnboardingState.ts | 🟢 P2 | - | 项目入门状态 |

---

### A.4 entrypoints/ 模块（8 个文件）

| 文件 | 级别 | Java 对应 | 说明 |
|------|------|----------|------|
| cli.tsx | 🔴 P0 | ClaudeCodeApplication | CLI 主入口（参数解析、快速路径、模式分发） |
| init.ts | 🟡 P1 | AppInitializer | 初始化入口 |
| mcp.ts | 🟢 P2 | - | MCP 服务器入口模式 |
| agentSdkTypes.ts | ⚪ P3 | - | Agent SDK 类型 |
| sandboxTypes.ts | ⚪ P3 | - | 沙箱类型 |
| sdk/*.ts | ⚪ P3 | - | SDK 核心（3个文件） |

---

### A.5 tools/ 模块（184 个文件，40 个工具）

#### 🔴 P0 核心工具（编码助手必备，11 个）

| # | 工具名 | 目录 | 文件数 | Java 类 | 说明 |
|---|-------|------|--------|---------|------|
| 1 | Bash | BashTool/ | 18 | BashTool | 执行 Shell/Cmd 命令，权限控制、沙箱隔离 |
| 2 | FileRead | FileReadTool/ | 5 | FileReadTool | 读取文件（文本/PDF/图片），Token计数 |
| 3 | FileEdit | FileEditTool/ | 6 | FileEditTool | 文件编辑（hunks、差异展示） |
| 4 | FileWrite | FileWriteTool/ | 3 | FileWriteTool | 写入文件，权限校验 |
| 5 | Glob | GlobTool/ | 3 | GlobTool | 文件名通配符搜索 |
| 6 | Grep | GrepTool/ | 3 | GrepTool | 基于 ripgrep 的代码搜索 |
| 7 | WebFetch | WebFetchTool/ | 5 | WebFetchTool | 获取网页内容 |
| 8 | WebSearch | WebSearchTool/ | 3 | WebSearchTool | 网络搜索 |
| 9 | AskUserQuestion | AskUserQuestionTool/ | 2 | AskUserTool | 向用户提问（多选/输入） |
| 10 | Agent | AgentTool/ | 20 | AgentTool | 子代理创建和运行 |
| 11 | PowerShell | PowerShellTool/ | 14 | (合并到BashTool) | Windows PowerShell 执行 |

#### 🟡 P1 重要工具（提升体验，8 个）

| # | 工具名 | 目录 | 文件数 | Java 类 | 说明 |
|---|-------|------|--------|---------|------|
| 12 | TodoWrite | TodoWriteTool/ | 3 | TodoWriteTool | 管理会话待办清单 |
| 13 | Skill | SkillTool/ | 4 | SkillTool | 执行技能/技能命令 |
| 14 | BriefTool | BriefTool/ | 5 | BriefTool | 向用户发送消息 |
| 15 | NotebookEdit | NotebookEditTool/ | 4 | - | Jupyter 笔记本编辑 |
| 16 | TaskStop | TaskStopTool/ | 3 | TaskStopTool | 停止后台任务 |
| 17 | TaskOutput | TaskOutputTool/ | 2 | TaskOutputTool | 获取任务输出 |
| 18 | EnterPlanMode | EnterPlanModeTool/ | 4 | PlanModeTool | 进入规划模式 |
| 19 | ExitPlanMode | ExitPlanModeTool/ | 4 | PlanModeTool | 退出规划模式 |

#### 🟢 P2 扩展工具（14 个）

| # | 工具名 | 目录 | 文件数 | 说明 |
|---|-------|------|--------|------|
| 20 | LSP | LSPTool/ | 6 | 语言服务器协议交互 |
| 21 | MCPTool | MCPTool/ | 4 | MCP 工具调用 |
| 22 | ListMcpResources | ListMcpResourcesTool/ | 3 | 列举 MCP 资源 |
| 23 | ReadMcpResource | ReadMcpResourceTool/ | 3 | 读取 MCP 资源 |
| 24 | McpAuth | McpAuthTool/ | 1 | MCP OAuth 认证 |
| 25 | Config | ConfigTool/ | 5 | 获取/设置配置 |
| 26 | ToolSearch | ToolSearchTool/ | 3 | 搜索延迟加载工具 |
| 27 | EnterWorktree | EnterWorktreeTool/ | 4 | Git 工作树隔离 |
| 28 | ExitWorktree | ExitWorktreeTool/ | 4 | 退出工作树 |
| 29 | TaskCreate | TaskCreateTool/ | 3 | 创建后台任务 |
| 30 | TaskGet | TaskGetTool/ | 3 | 获取任务信息 |
| 31 | TaskList | TaskListTool/ | 3 | 列出后台任务 |
| 32 | TaskUpdate | TaskUpdateTool/ | 3 | 更新任务状态 |
| 33 | SendMessage | SendMessageTool/ | 4 | 代理间消息 |

#### ⚪ P3 跳过工具（7 个，特定平台/功能门控）

| # | 工具名 | 说明 |
|---|-------|------|
| 34 | REPL | Ant 内部专用 |
| 35 | TeamCreate/Delete | Agent Swarm 模式 |
| 36 | RemoteTrigger | 远程触发器 |
| 37 | ScheduleCron(3个) | Cron 定时任务 |
| 38 | Sleep | 延迟等待 |
| 39 | SyntheticOutput | 结构化输出 |
| 40 | 测试工具 | TestingPermissionTool |

---

### A.6 commands/ 模块（207 个文件，79+ 命令）

#### 🔴 P0 核心命令（用户基础操作，14 个）

| 命令 | 别名 | Java 类 | 说明 |
|------|------|---------|------|
| /help | - | HelpCommand | 显示帮助和可用命令列表 |
| /clear | reset, new | ClearCommand | 清除对话历史 |
| /compact | - | CompactCommand | 压缩上下文（保留摘要） |
| /exit | quit | ExitCommand | 退出应用 |
| /model | - | ModelCommand | 切换 AI 模型 |
| /config | settings | ConfigCommand | 打开配置面板 |
| /context | - | ContextCommand | 显示当前上下文使用情况 |
| /memory | - | MemoryCommand | 编辑 CLAUDE.md 记忆文件 |
| /cost | - | CostCommand | 显示费用和 Token 消耗 |
| /status | - | StatusCommand | 显示状态（版本、模型、账户） |
| /diff | - | DiffCommand | 查看未提交变更 |
| /copy | - | CopyCommand | 复制最近回复到剪贴板 |
| /version | - | VersionCommand | 显示版本号 |
| /skills | - | SkillsCommand | 列出可用技能 |

#### 🟡 P1 重要命令（常用功能，16 个）

| 命令 | 别名 | Java 类 | 说明 |
|------|------|---------|------|
| /commit | - | CommitCommand | 创建 git commit |
| /resume | continue | ResumeCommand | 恢复之前的对话 |
| /add-dir | - | AddDirCommand | 添加工作目录 |
| /theme | - | ThemeCommand | 切换主题（暗色/亮色） |
| /plan | - | PlanCommand | 进入/查看规划模式 |
| /permissions | allowed-tools | PermissionsCommand | 管理工具权限规则 |
| /export | - | ExportCommand | 导出对话到文件 |
| /rename | - | RenameCommand | 重命名当前对话 |
| /effort | - | EffortCommand | 设置模型投入级别 |
| /fast | - | FastCommand | 切换快速模式 |
| /vim | - | VimCommand | 切换 Vim/普通编辑模式 |
| /keybindings | - | KeybindingsCommand | 快捷键配置 |
| /files | - | FilesCommand | 列出当前上下文中的文件 |
| /doctor | - | DoctorCommand | 诊断安装和设置 |
| /tasks | bashes | TasksCommand | 管理后台任务 |
| /usage | - | UsageCommand | 显示计划使用限制 |

#### 🟢 P2 扩展命令（22 个）

| 命令 | 说明 |
|------|------|
| /review | 审查 Pull Request |
| /commit-push-pr | 提交、推送并开 PR |
| /branch | 创建对话分支 |
| /rewind | 回退到之前的检查点 |
| /mcp | 管理 MCP 服务器 |
| /hooks | 查看钩子配置 |
| /login, /logout | 登录/登出 |
| /color | 设置提示栏颜色 |
| /ide | 管理 IDE 集成 |
| /init | 初始化项目文档 |
| /feedback | 提交反馈 |
| /share | 分享对话 |
| /session | 远程会话 |
| /plugin | 管理插件 |
| /pr-comments | 获取 PR 评论 |
| /release-notes | 查看发布说明 |
| /security-review | 安全审查 |
| /desktop | 转到 Claude Desktop |
| /mobile | 显示移动端二维码 |
| /sandbox | 管理沙箱设置 |
| /stats | 使用统计 |
| /tag | 会话标签 |

#### ⚪ P3 跳过命令（27+ 个，内部/调试/平台特定）

debug-tool-call, heapdump, perf-issue, bridge-kick, ant-trace, mock-limits,
backfill-sessions, break-cache, good-claude, autofix-pr, bughunter,
teleport, stickers, ultraplan, upgrade, install-github-app, install-slack-app,
chrome, voice, brief, proactive, assistant, remote-control, statusline,
thinkback, thinkback-play, oauth-refresh 等

---

### A.7 services/ 模块（130 个文件，20 个子模块）

| 子模块 | 文件数 | 级别 | Java 对应 | 说明 |
|--------|--------|------|----------|------|
| api/ | 19 | 🔴 P0 | AiService / ApiClient | AI API 调用（Anthropic SDK、重试、错误处理） |
| tools/ | 4 | 🔴 P0 | ToolExecutor | 工具执行框架（StreamingToolExecutor、工具钩子） |
| compact/ | 10 | 🟡 P1 | CompactService | 上下文压缩（自动/手动压缩、消息分组） |
| mcp/ | 22 | 🟢 P2 | McpService | MCP 客户端（StdIO/SSE/HTTP 传输、认证） |
| oauth/ | 5 | 🟢 P2 | OAuthService | OAuth 认证流程 |
| analytics/ | 10 | ⚪ P3 | - | 分析和遥测（Datadog、GrowthBook） |
| lsp/ | 6 | 🟢 P2 | LspService | 语言服务器集成 |
| SessionMemory/ | 3 | 🟡 P1 | SessionMemoryService | 会话记忆管理 |
| extractMemories/ | 2 | 🟡 P1 | MemoryExtractor | 从对话中提取记忆 |
| autoDream/ | 4 | ⚪ P3 | - | 自动任务执行引擎 |
| plugins/ | 若干 | 🟢 P2 | PluginService | 插件服务接口 |
| PromptSuggestion/ | 若干 | 🟢 P2 | - | 提示词建议 |
| tips/ | 若干 | ⚪ P3 | - | 使用提示 |
| remoteManagedSettings/ | 若干 | ⚪ P3 | - | 远程管理设置 |
| settingsSync/ | 若干 | ⚪ P3 | - | 设置同步 |
| teamMemorySync/ | 若干 | ⚪ P3 | - | 团队记忆同步 |
| AgentSummary/ | 若干 | 🟢 P2 | - | 代理摘要生成 |
| tokenEstimation.ts | 1 | 🟡 P1 | TokenEstimator | Token 数量估算 |
| voice*.ts | 3 | ⚪ P3 | - | 语音功能 |
| rateLimitMessages.ts | 1 | 🟡 P1 | RateLimitHandler | 速率限制消息 |

---

### A.8 components/ 模块（389 个文件）

> 原版使用 React + Ink 渲染终端 UI，Java 版本使用 JLine 3 + ANSI 替代，不直接映射 React 组件，而是提取其 **渲染逻辑** 用 Java 实现。

| 子模块/组件 | 级别 | Java 对应 | 说明 |
|------------|------|----------|------|
| LogoV2/ (Banner) | 🔴 P0 | BannerPrinter | 启动 Banner（ASCII Art + 版本 + 模型） |
| PromptInput/ | 🔴 P0 | InputPrompt | 命令输入框（多行、历史、补全） |
| Messages.tsx | 🔴 P0 | MessageRenderer | 消息列表渲染 |
| messages/AssistantThinkingMessage | 🔴 P0 | ThinkingRenderer | Thinking 过程显示（∴ Thinking...） |
| messages/AssistantToolUseMessage | 🔴 P0 | ToolStatusRenderer | 工具调用状态显示 |
| Spinner.tsx | 🔴 P0 | SpinnerAnimation | 加载动画（shimmer 效果） |
| ToolUseLoader.tsx | 🔴 P0 | (集成到ToolStatusRenderer) | 工具加载指示（●成功/●失败） |
| StatusLine.tsx | 🟡 P1 | StatusLineRenderer | 底部状态行（模型、权限模式、cwd） |
| AgentProgressLine.tsx | 🟡 P1 | AgentProgressRenderer | Agent 执行进度（树形结构） |
| TextInput.tsx | 🔴 P0 | (集成到InputPrompt) | 文本输入（Vim模式支持） |
| design-system/ | 🟡 P1 | AnsiStyle | 设计系统（主题色、ThemedBox/Text） |
| HighlightedCode/ | 🟡 P1 | MarkdownRenderer | 代码语法高亮 |
| diff/ | 🟢 P2 | DiffRenderer | 差异视图显示 |
| permissions/ | 🟡 P1 | PermissionPrompt | 权限请求对话框 |
| HelpV2/ | 🟡 P1 | (集成到HelpCommand) | 帮助面板 |
| mcp/ | 🟢 P2 | - | MCP 服务器 UI |
| agents/ | 🟢 P2 | - | 多代理管理 UI |
| tasks/ | 🟡 P1 | TaskListRenderer | 任务列表 UI |
| wizard/ | ⚪ P3 | - | 向导组件 |
| sandbox/ | ⚪ P3 | - | 沙箱 UI |
| grove/ | ⚪ P3 | - | Grove 框架 UI |

---

### A.9 ink/ 模块（96 个文件）

> 自定义 Ink 终端 UI 框架（React reconciler + Yoga 布局）。Java 版本不移植此框架，而是用 JLine 3 直接实现终端渲染。

| 子模块 | 级别 | Java 对应 | 说明 |
|--------|------|----------|------|
| 渲染引擎 | ⚪ P3 | - | React reconciler + Yoga 布局 → 不适用 |
| components/ (Box, Text...) | ⚪ P3 | - | 基础UI组件 → JLine 直接输出替代 |
| hooks/ (useInput, useAnimationFrame...) | ⚪ P3 | - | React Hooks → Java 事件循环替代 |
| events/ | 🔴 P0 | JLine KeyMap | 键盘/鼠标事件 → JLine 事件处理 |
| terminal.ts | 🔴 P0 | JLine Terminal | 终端交互 → JLine Terminal |
| colorize.ts | 🔴 P0 | AnsiStyle | 着色 → ANSI 转义码 |
| stringWidth.ts | 🟡 P1 | StringWidthUtil | 字符串宽度计算（CJK支持） |
| wrap-text.ts | 🟡 P1 | TextWrapper | 文本换行 |

---

### A.10 hooks/ 模块（104 个文件）

> React Hooks 模式不直接移植。提取关键业务逻辑到 Java 服务类。

| 关键 Hook | 级别 | Java 对应 | 说明 |
|-----------|------|----------|------|
| useMainLoopModel | 🔴 P0 | AgentLoop | 主循环模型管理 |
| useCommandQueue | 🔴 P0 | CommandQueue | 命令队列 |
| useCanUseTool | 🔴 P0 | PermissionChecker | 工具权限检查 |
| useMergedTools | 🔴 P0 | ToolRegistry | 工具合并（内置+MCP） |
| useMergedCommands | 🔴 P0 | CommandRegistry | 命令合并 |
| useTextInput | 🔴 P0 | InputPrompt | 文本输入处理 |
| useArrowKeyHistory | 🟡 P1 | (JLine 内置) | 方向键历史导航 |
| useVimInput | 🟡 P1 | VimModeHandler | Vim 模式输入 |
| useGlobalKeybindings | 🟡 P1 | KeybindingManager | 全局快捷键 |
| useElapsedTime | 🟡 P1 | CostTracker | 耗时计算 |
| useIDEIntegration | ⚪ P3 | - | IDE 集成 |
| useVoice* | ⚪ P3 | - | 语音相关 |
| useRemoteSession | ⚪ P3 | - | 远程会话 |
| useTeleportResume | ⚪ P3 | - | 传送恢复 |
| notifs/ (16个) | 🟢 P2 | NotificationService | 各类通知 |

---

### A.11 utils/ 模块（564 个文件，31 个子目录）

| 子模块 | 文件数 | 级别 | Java 对应 | 说明 |
|--------|--------|------|----------|------|
| shell/ | 10 | 🔴 P0 | ShellExecutor | Shell 命令执行框架 |
| permissions/ | 22 | 🔴 P0 | PermissionService | 权限验证（分类器、规则解析、危险模式） |
| claudemd.ts | 1 | 🔴 P0 | ClaudeMdLoader | CLAUDE.md 查找和加载（含 @include） |
| systemPrompt.ts | 1 | 🔴 P0 | SystemPromptBuilder | 系统提示词构建 |
| config.ts | 1 | 🔴 P0 | ConfigManager | 配置加载管理 |
| git/ | 3 | 🔴 P0 | GitContext | Git 操作（分支、状态、日志） |
| file.ts + fileRead*.ts | 5 | 🔴 P0 | FileUtils | 文件操作工具 |
| model/ | 5 | 🟡 P1 | ModelSelector | 模型选择和成本计算 |
| hooks/ | 16 | 🟡 P1 | HookExecutor | 钩子系统（PreToolUse/PostToolUse） |
| plugins/ | 38 | 🟢 P2 | PluginLoader | 插件加载和管理 |
| skills/ | 1 | 🟡 P1 | SkillWatcher | 技能变更检测 |
| todo/ | 若干 | 🟡 P1 | TodoManager | TODO 任务追踪 |
| messages/ | 2 | 🔴 P0 | MessageMapper | 消息格式映射 |
| json.ts, markdown.ts | 2 | 🟡 P1 | FormatUtils | 数据格式处理 |
| diff.ts, gitDiff.ts | 2 | 🟡 P1 | DiffUtils | 差异比较 |
| auth.ts, oauth/ | 3 | 🟢 P2 | AuthUtils | 认证工具 |
| telemetry/ | 9 | ⚪ P3 | - | 遥测和追踪 |
| sandbox/ | 2 | ⚪ P3 | - | 沙箱隔离 |
| swarm/ | 若干 | ⚪ P3 | - | Swarm 多代理 |
| computerUse/ | 14 | ⚪ P3 | - | 计算机控制 |
| teleport/ | 若干 | ⚪ P3 | - | 会话传送 |
| suggestions/ | 若干 | 🟢 P2 | - | 建议系统 |

---

### A.12 其他模块

| 模块 | 文件数 | 级别 | Java 对应 | 说明 |
|------|--------|------|----------|------|
| skills/ | 20 | 🟡 P1 | SkillLoader + skills/ | 技能系统（17 个内置技能、磁盘加载） |
| state/ | 6 | 🔴 P0 | SessionState | 全局状态管理 |
| constants/ | 21 | 🔴 P0 | Constants + Prompts | 常量和系统提示词定义 |
| types/ | 11 | 🔴 P0 | (分散到各接口) | 类型定义 |
| screens/ | 3 | 🔴 P0 | ReplSession | REPL/Doctor/Resume 屏幕 |
| cli/ | 19 | 🔴 P0 | CliOutput | CLI 输出处理 |
| context/ | 9 | 🟡 P1 | (Spring Context替代) | React Context 状态管理 |
| keybindings/ | 14 | 🟡 P1 | KeybindingManager | 快捷键系统 |
| memdir/ | 8 | 🟡 P1 | MemoryManager | 记忆库/记忆查找 |
| tasks/ | 12 | 🟡 P1 | TaskExecutor | 后台任务执行 |
| query/ | 4 | 🔴 P0 | AgentLoop | 查询系统、Token预算 |
| vim/ | 5 | 🟡 P1 | VimModeHandler | Vim 编辑模式 |
| migrations/ | 11 | ⚪ P3 | - | 数据迁移 |
| bridge/ | 31 | ⚪ P3 | - | IDE 桥接 |
| buddy/ | 6 | ⚪ P3 | - | 伙伴系统 |
| coordinator/ | 1 | 🟢 P2 | - | 多代理协调 |
| remote/ | 4 | ⚪ P3 | - | 远程连接 |
| server/ | 3 | ⚪ P3 | - | 直连服务器 |
| native-ts/ | 4 | ⚪ P3 | - | 原生 C++ 扩展 |
| upstreamproxy/ | 2 | ⚪ P3 | - | 代理中继 |
| plugins/ | 2 | 🟢 P2 | PluginManager | 插件系统框架 |
| outputStyles/ | 1 | 🟢 P2 | OutputStyleLoader | 自定义输出样式 |
| voice/ | 1 | ⚪ P3 | - | 语音模式 |
| moreright/ | 1 | ⚪ P3 | - | UI 增强 |
| bootstrap/ | 1 | 🔴 P0 | (AppConfig) | 启动状态 |
| assistant/ | 1 | 🟡 P1 | SessionHistoryApi | 会话历史 API |
| schemas/ | 1 | 🔴 P0 | (分散到各Schema) | 数据模式 |

---

### A.13 覆盖统计汇总

| 级别 | 模块/组件数 | 说明 |
|------|-----------|------|
| 🔴 P0 核心 | ~45 | 不实现则系统无法运行 |
| 🟡 P1 重要 | ~35 | 影响核心用户体验 |
| 🟢 P2 扩展 | ~25 | 增强功能，可后续迭代 |
| ⚪ P3 跳过 | ~30 | 平台特定或不适用 |

### Java 版最终类数估算

| 层次 | 预估类数 | 说明 |
|------|---------|------|
| CLI 层 | 3-5 | Application、Command、Runner |
| 核心层 | 5-8 | AgentLoop、MessageHistory、SessionState 等 |
| 工具层 | 12-15 | 11 个核心工具 + Registry + Callback |
| 命令层 | 16-20 | 14 个核心命令 + Registry + 接口 |
| 上下文层 | 6-8 | ContextBuilder、PromptBuilder、ClaudeMd、Git、Skill |
| 渲染层 | 8-12 | Console、Banner、Thinking、ToolStatus、Markdown、Spinner 等 |
| 配置层 | 3-5 | AppConfig、AiConfig、ToolConfig |
| **总计** | **55-75** | |