FreeloadingCode
/
claude-code
mirror of https://gitee.com/free/claude-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
21 Commits
4 Branches
1 Tag
12 MiB
 
Tag: Branch: Tree: 7dc4d142b3
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '7dc4d142b3'
${ noResults }
claude-code/需求文档.md

32 KiB
Raw Blame History

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）：

---
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