From 2a565d314d73d27e535ddd99b37f9b133fc6a256 Mon Sep 17 00:00:00 2001 From: liuzh Date: Wed, 1 Apr 2026 19:03:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E9=9C=80=E6=B1=82=E6=96=87=E6=A1=A3=E5=92=8C=E4=BF=AE?= =?UTF-8?q?=E6=94=B9=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建需求文档.md：完整覆盖 claude-code 全部 38 个模块、2289 个文件 - 按 P0/P1/P2/P3 四级划分实现优先级 - 包含工具系统(40个)、命令系统(79+个)、服务层(20个子模块)的完整映射 - 设计 Java 包结构和类映射关系 - 创建修改记录.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- 修改记录.md | 14 + 需求文档.md | 712 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 726 insertions(+) create mode 100644 修改记录.md create mode 100644 需求文档.md diff --git a/修改记录.md b/修改记录.md new file mode 100644 index 0000000..4ecfe75 --- /dev/null +++ b/修改记录.md @@ -0,0 +1,14 @@ +# 修改记录 + +## [2026-04-02] - 项目初始化与需求分析 + +- **修改类型**: 文档更新 +- **修改详情**: + - 创建 `需求文档.md`，完成需求分析和技术设计 + - 创建 `修改记录.md`，记录项目变更历史 + - 完成 claude-code TypeScript 源码的主线逻辑分析 + - 完成 claude-code-learn Java 参考实现的架构分析 + - 确定 Java 重写的技术栈：JDK 25 + Spring Boot 3.5.x + Spring AI 2.0.0-M4 + JLine 3 + Picocli + - 设计包结构和类映射关系 + - 划分 6 个实现阶段 +- **关联需求**: 全部章节 diff --git a/需求文档.md b/需求文档.md new file mode 100644 index 0000000..760ddb6 --- /dev/null +++ b/需求文档.md @@ -0,0 +1,712 @@ +# 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` 流式响应 +- 实时渲染 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` + - 不依赖 Spring AI 的 ChatMemory + - 精确控制消息格式和截断 + +4. **终端 UI**: JLine 3 + ANSI 转义码 + - 不使用 React 渲染模型（原版 Ink 方式） + - 直接操作终端输出流 + - 支持 Windows Terminal / PowerShell + +## 4. 验收标准 + +### 4.1 基础功能 +- [ ] 应用可正常启动并显示 Banner +- [ ] 支持通过环境变量或配置文件设置 API Key 和模型 +- [ ] REPL 循环正常工作：输入问题 → 获得 AI 回复 +- [ ] 工具调用循环正常：AI 可以调用工具并获取结果 +- [ ] 至少支持 8 个核心工具（Bash、FileRead、FileWrite、FileEdit、Glob、Grep、WebFetch、TodoWrite） +- [ ] 至少支持 8 个斜杠命令（/help、/clear、/compact、/exit、/cost、/model、/memory、/context） + +### 4.2 交互体验 +- [ ] Banner 显示正常（Logo + 版本 + 模型信息） +- [ ] 输入提示符支持行编辑和历史记录 +- [ ] Thinking 过程可见 +- [ ] 工具调用时显示 Spinner 动画和状态 +- [ ] 支持 ANSI 颜色输出 +- [ ] Markdown 内容基本格式化 + +### 4.3 上下文功能 +- [ ] 能加载项目 CLAUDE.md +- [ ] 能加载用户级 CLAUDE.md +- [ ] Git 上下文信息正确收集 +- [ ] 系统提示词包含所有必要信息 + +### 4.4 代码质量 +- [ ] Maven 编译无错误 +- [ ] 代码结构清晰，包划分合理 +- [ ] 关键逻辑有中文注释 +- [ ] 提供完整的使用文档 + +--- + +## 附录 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** | |