docs: 初始化项目需求文档和修改记录

- 创建需求文档.md：完整覆盖 claude-code 全部 38 个模块、2289 个文件 - 按 P0/P1/P2/P3 四级划分实现优先级 - 包含工具系统(40个)、命令系统(79+个)、服务层(20个子模块)的完整映射 - 设计 Java 包结构和类映射关系 - 创建修改记录.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 month ago · 2a565d314d
commit 2a565d314d
2 changed files with 726 additions and 0 deletions
--- a/修改记录.md
+++ 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 个实现阶段
+- **关联需求**: 全部章节
--- a/需求文档.md
+++ 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<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 基础功能
+- [ ] 应用可正常启动并显示 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** | |