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

---
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 个核心工具（实际 18 个）
• 至少支持 8 个斜杠命令（实际 28 个）

4.2 交互体验

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

4.3 上下文功能

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

4.4 代码质量

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

4.5 已超出原始验收标准的功能

• 流式输出（Flux 逐 token 实时显示）
• 对话历史持久化（JSON 格式自动保存/加载）
• AI 驱动的上下文压缩（/compact 生成摘要）
• 多行输入支持（反斜杠续行）
• 双 API 提供者（OpenAI + Anthropic 切换）
• /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加载)	✅
	任务管理系统	✅
	对话分支/标签/回退	✅
CLI 样式	边框 Banner (╭╮╰╯ + Logo)	✅
	彩色 ● 圆点消息标识	✅
	⎿ 工具结果前缀	✅
	<thought> 标签思考显示	✅
	✻ 耗时统计	✅
i18n	用户可见字符串统一英文	✅

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