docs: 全面更新文档 - README/需求文档/修改记录

README.md: - 功能特性分 P0/P1/P2 三级展示 - 工具列表更新为 18 个（含 P0/P2 工具） - 命令列表更新为 28 个（分基础/P0/P1/P2 四组） - 新增 MCP 服务器配置和使用说明 - 新增插件系统使用说明（JAR 加载、目录结构） - 新增 Vim 模式和 Hook 系统使用说明 - 架构图更新：含 mcp/、plugin/、core/ 新组件 - 核心流程图更新：含 Hook 和权限确认 - 对应关系表新增 MCP/Plugin/Hook/Task 映射需求文档.md: - 5.1 实现清单更新为 18 工具 + 28 命令 - 5.2 P0/P1/P2 标记为全部已实现 - 仅保留 P3 跳过项目修改记录.md: - 新增 P0/P1/P2 四条修改记录（倒序排列） Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-01 23:04:01 +08:00
parent 79736cf16f
commit 1fc7a6a495
6 changed files with 411 additions and 112 deletions
@@ -4,16 +4,35 @@

 ## ✨ 功能特性

+### 核心功能
 - 🤖 **AI 对话** — 流式输出，逐 token 实时显示
- 🔧 **11 个内置工具** — Bash、文件读写编辑、Glob、Grep、Web获取、Agent 等
+- 🔧 **18 个内置工具** — Bash、文件操作、搜索、Web、任务管理、MCP桥接 等
 - ⚡ **双 API 提供者** — 同时支持 OpenAI 兼容 API 和 Anthropic 原生 API
- 📝 **斜杠命令** — `/help`, `/compact`, `/cost`, `/model`, `/history` 等 11 个命令
- 🖥️ **JLine 终端** — 行编辑、历史记录、Tab 补全、多行输入
+- 📝 **28 个斜杠命令** — 从基础操作到代码审查、安全分析、对话管理
+- 🖥️ **JLine 终端** — 行编辑、历史记录、Tab 补全、多行输入、Vim 模式
 - 📋 **CLAUDE.md** — 自动加载项目级和用户级记忆文件
 - 🎯 **Skills** — 可扩展的技能系统
 - 🌿 **Git 上下文** — 自动收集分支、状态、最近提交
- 💾 **对话持久化** — 自动保存对话历史，支持回顾
- 🗜️ **上下文压缩** — AI 生成摘要替代简单清空
+
+### P0 核心增强
+- 🔒 **权限确认** — 危险操作（文件写入、Bash执行）前要求用户确认 [Y/n/always]
+- 💭 **Thinking 显示** — 展示 AI 思考过程（Anthropic extended thinking）
+- 🔍 **WebSearch** — DuckDuckGo 网络搜索（无需 API Key）
+- ❓ **AskUser** — AI 在执行过程中向用户提问
+
+### P1 体验增强
+- 📊 **底部状态行** — 持续显示模型、Token、费用、工作目录
+- 🪝 **Hook 系统** — PreToolUse/PostToolUse/PrePrompt/PostResponse 4 种钩子
+- 🎨 **代码语法高亮** — 支持 Java/JS/TS/Python/Bash/SQL 6 种语言
+- ⌨️ **Vim 模式** — JLine vi 编辑模式（`CLAUDE_CODE_VIM=1` 启用）
+
+### P2 扩展功能
+- 🔌 **MCP 协议** — Model Context Protocol 客户端（StdIO 传输、工具发现、资源读取）
+- 🧩 **插件系统** — JAR 插件加载（ClassLoader 隔离、工具/命令扩展）
+- 📋 **任务管理** — 后台任务创建、查询、更新（4 个工具）
+- 🔀 **彩色 Diff** — unified diff 渲染（行号、stat 摘要、颜色标注）
+- 🌿 **对话分支** — 保存/恢复/标签对话状态
+- 🛡️ **安全审查** — AI 驱动的安全漏洞检测

 ## 📦 技术栈

@@ -85,7 +104,7 @@ mvn spring-boot:run
  Provider: OPENAI  Model: deepseek-chat
  API URL:  https://api.deepseek.com
  Work Dir: D:\my-project
-  Tools: 11 registered
+  Tools: 18 | Commands: 28
  Terminal: windows-vtp (160×30)
  Tip: Tab to complete commands, ↑↓ to browse history, Ctrl+D to exit

@@ -113,24 +132,60 @@ mvn spring-boot:run

 ### 斜杠命令

-| 命令 | 说明 |
-|------|------|
-| `/help` | 显示所有可用命令 |
-| `/clear` | 清屏 |
-| `/compact` | AI 摘要压缩对话上下文 |
-| `/cost` | 显示 Token 使用量和费用 |
-| `/model [name]` | 查看/切换模型 |
-| `/status` | 显示会话状态（消息数、Token、模型） |
-| `/context` | 显示已加载的上下文（CLAUDE.md、Skills、Git） |
-| `/config` | 查看配置信息 |
-| `/init` | 初始化 CLAUDE.md 配置文件 |
-| `/history` | 列出保存的对话历史 |
-| `/exit` | 退出 |
+#### 基础命令
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `/help` | | 显示所有可用命令 |
+| `/clear` | | 清屏 |
+| `/compact` | | AI 摘要压缩对话上下文 |
+| `/cost` | | 显示 Token 使用量和费用 |
+| `/model [name]` | | 查看/切换模型 |
+| `/status` | | 显示会话状态 |
+| `/context` | | 显示已加载的上下文 |
+| `/config` | | 查看配置信息 |
+| `/init` | | 初始化 CLAUDE.md 配置文件 |
+| `/history` | | 列出保存的对话历史 |
+| `/exit` | `/quit` | 退出 |
+
+#### P0 命令
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `/diff` | | 显示 Git 变更（支持 `--staged`, `--stat`） |
+| `/version` | `/ver` | 显示版本和环境信息 |
+| `/skills` | | 列出已加载的技能 |
+| `/memory` | `/mem` | 查看/编辑 CLAUDE.md |
+| `/copy` | | 复制最近回复到剪贴板 |
+
+#### P1 命令
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `/resume` | | 恢复已保存的对话 |
+| `/export` | | 导出对话为 Markdown 文件 |
+| `/commit` | | AI 生成 commit message 并提交 |
+
+#### P2 命令
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `/hooks` | | 查看已注册的 Hook |
+| `/review` | `/rev` | AI 代码审查（支持 `--staged`、文件路径） |
+| `/stats` | | 使用统计（Token、费用、API调用、运行时长） |
+| `/branch` | | 对话分支（`save/load/list/delete`） |
+| `/rewind [n]` | | 回退对话历史（默认回退1轮） |
+| `/tag` | | 对话标签（`<name>/list/goto <name>`） |
+| `/security-review` | `/sec` | AI 安全漏洞审查 |
+| `/mcp` | | MCP 服务器管理（`connect/disconnect/tools/resources`） |
+| `/plugin` | | 插件管理（`load/unload/reload/info`） |

 ### 内置工具

 AI 可以自动调用以下工具：

+#### 核心工具（Phase 1-3）
+
 | 工具 | 说明 |
 |------|------|
 | `bash` | 执行 Shell 命令 |
@@ -145,6 +200,24 @@ AI 可以自动调用以下工具：
 | `agent` | 启动子 Agent 处理复杂任务 |
 | `notebook_edit` | 编辑 Jupyter Notebook |

+#### P0 工具
+
+| 工具 | 说明 |
+|------|------|
+| `web_search` | DuckDuckGo 网络搜索（无需 API Key） |
+| `ask_user_question` | AI 向用户提问（暂停 agent loop 等待输入） |
+
+#### P2 工具
+
+| 工具 | 说明 |
+|------|------|
+| `TaskCreate` | 创建后台任务 |
+| `TaskGet` | 查询任务详情 |
+| `TaskList` | 列出任务（支持状态过滤） |
+| `TaskUpdate` | 更新任务状态和结果 |
+| `Config` | 读写配置值 |
+| `mcp__*` | MCP 远程工具桥接（动态注册） |
+
 ### CLAUDE.md 记忆文件

 创建 `CLAUDE.md` 文件来给 AI 提供项目上下文：
@@ -185,6 +258,81 @@ description: 代码审查技能
 3. 性能考量
 ```

+### MCP 服务器集成
+
+配置 MCP 服务器，在项目根目录创建 `.mcp.json`：
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    },
+    "my-server": {
+      "command": "python",
+      "args": ["my_mcp_server.py"],
+      "env": { "API_KEY": "xxx" }
+    }
+  }
+}
+```
+
+或放在全局目录 `~/.claude-code-java/mcp.json`。
+
+使用 `/mcp` 命令管理：
+```
+❯ /mcp                          # 列出所有 MCP 服务器
+❯ /mcp tools                    # 列出所有 MCP 工具
+❯ /mcp connect myserver cmd args # 连接新服务器
+❯ /mcp disconnect myserver      # 断开服务器
+```
+
+### 插件系统
+
+JAR 插件放在以下目录即可自动加载：
+- `~/.claude-code-java/plugins/` — 全局插件
+- `.claude-code/plugins/` — 项目级插件
+
+JAR 要求：
+- `META-INF/MANIFEST.MF` 中包含 `Plugin-Class` 属性
+- 实现 `com.claudecode.plugin.Plugin` 接口
+
+使用 `/plugin` 命令管理：
+```
+❯ /plugin                      # 列出已加载插件
+❯ /plugin info output-style    # 查看插件详情
+❯ /plugin unload my-plugin     # 卸载插件
+```
+
+### Vim 模式
+
+设置环境变量启用 JLine vi 编辑模式：
+
+```bash
+export CLAUDE_CODE_VIM=1
+```
+
+启用后 Banner 会显示 `[vim]` 标识，输入行支持 vi 按键绑定。
+
+### Hook 系统
+
+通过代码注册 Hook 来拦截工具调用：
+
+```java
+agentLoop.getHookManager().register(HookManager.HookType.PRE_TOOL_USE, new Hook() {
+    public String name() { return "my-hook"; }
+    public int priority() { return 10; }
+    public HookResult execute(HookContext ctx) {
+        // 可检查 ctx.getToolName(), ctx.getArguments()
+        // 返回 ABORT 可阻止工具执行
+        return HookResult.CONTINUE;
+    }
+});
+```
+
+4 种钩子类型：`PRE_TOOL_USE`、`POST_TOOL_USE`、`PRE_PROMPT`、`POST_RESPONSE`
+
 ## 🏗️ 架构设计

 ### 模块结构
@@ -195,32 +343,54 @@ com.claudecode
 ├── cli/
 │   └── ClaudeCodeRunner           // 启动编排（CommandLineRunner）
 ├── config/
-│   └── AppConfig                  // Bean 装配、Provider 切换
+│   └── AppConfig                  // Bean 装配、Provider 切换、组件注册
 ├── core/
-│   ├── AgentLoop                  // Agent 循环（阻塞 + 流式）
+│   ├── AgentLoop                  // Agent 循环（阻塞 + 流式 + Hook集成）
 │   ├── TokenTracker               // Token 使用追踪
-│   └── ConversationPersistence    // 对话持久化
+│   ├── ConversationPersistence    // 对话持久化
+│   ├── HookManager                // Hook 系统（4种钩子类型）
+│   └── TaskManager                // 后台任务管理
 ├── tool/
 │   ├── Tool                       // 工具协议接口
 │   ├── ToolRegistry               // 工具注册中心
 │   ├── ToolCallbackAdapter        // Spring AI 适配器
-│   └── impl/                      // 11 个工具实现
+│   └── impl/                      // 18 个工具实现
+│       ├── BashTool, FileReadTool, FileWriteTool, FileEditTool
+│       ├── GlobTool, GrepTool, ListFilesTool, WebFetchTool
+│       ├── TodoWriteTool, AgentTool, NotebookEditTool
+│       ├── WebSearchTool, AskUserQuestionTool
+│       ├── TaskCreateTool, TaskGetTool, TaskListTool, TaskUpdateTool
+│       ├── ConfigTool
+│       └── McpToolBridge          // MCP 远程工具桥接
 ├── command/
 │   ├── SlashCommand               // 命令接口
 │   ├── CommandRegistry            // 命令注册中心
-│   └── impl/                      // 11 个命令实现
+│   └── impl/                      // 28 个命令实现
 ├── console/
 │   ├── BannerPrinter              // 启动 Banner
 │   ├── ToolStatusRenderer         // 工具状态渲染
 │   ├── ThinkingRenderer           // Thinking 渲染
 │   ├── SpinnerAnimation           // 加载动画
-│   ├── MarkdownRenderer           // Markdown 渲染
+│   ├── MarkdownRenderer           // Markdown 渲染（含语法高亮）
+│   ├── DiffRenderer               // 彩色 Diff 渲染
+│   ├── StatusLine                 // 底部状态行
 │   └── AnsiStyle                  // ANSI 样式工具
 ├── context/
 │   ├── SystemPromptBuilder        // 系统提示词构建
 │   ├── ClaudeMdLoader             // CLAUDE.md 加载
 │   ├── SkillLoader                // Skills 加载
 │   └── GitContext                 // Git 上下文收集
+├── mcp/
+│   ├── McpClient                  // MCP 客户端（JSON-RPC 2.0）
+│   ├── McpTransport               // 传输层接口
+│   ├── StdioTransport             // StdIO 传输实现
+│   ├── McpManager                 // 多服务器管理
+│   └── McpException               // MCP 异常
+├── plugin/
+│   ├── Plugin                     // 插件接口
+│   ├── PluginContext              // 插件上下文
+│   ├── PluginManager              // 插件加载/管理
+│   └── OutputStylePlugin          // 内置输出样式插件
 └── repl/
    ├── ReplSession                // REPL 会话管理
    └── ClaudeCodeCompleter        // Tab 补全
@@ -235,11 +405,39 @@ com.claudecode
                        ↓
              逐token实时输出到终端
                        ↓
-              检测工具调用 → 执行工具 → 结果回传
+              检测工具调用 → PreToolUse Hook → 权限确认 → 执行工具 → PostToolUse Hook → 结果回传
                        ↓
              继续循环或结束
 ```

+### MCP 协议架构
+
+```
+McpManager ─── 配置加载 (.mcp.json)
+    │
+    ├── McpClient("server-a") ── StdioTransport ── 子进程 (npx server-a)
+    │       ├── tools/list → 发现工具
+    │       ├── tools/call → 调用工具
+    │       └── resources/read → 读取资源
+    │
+    └── McpClient("server-b") ── StdioTransport ── 子进程 (python server-b)
+            └── ... (同上)
+
+McpToolBridge → 将 MCP 工具映射为本地 Tool → 注册到 ToolRegistry → AI 可调用
+```
+
+### 插件系统架构
+
+```
+PluginManager
+    ├── 全局插件: ~/.claude-code-java/plugins/*.jar
+    ├── 项目插件: .claude-code/plugins/*.jar
+    └── 内置插件: OutputStylePlugin
+        │
+        ├── Plugin.getTools() → 注册到 ToolRegistry
+        └── Plugin.getCommands() → 注册到 CommandRegistry
+```
+
 ### 双 API 提供者架构

 ```
@@ -279,6 +477,7 @@ claude-code:
 | `AI_BASE_URL` | ❌ | API 基础 URL | 按提供者不同 |
 | `AI_MODEL` | ❌ | 模型名称 | 按提供者不同 |
 | `AI_MAX_TOKENS` | ❌ | 最大 Token 数 | `8096` |
+| `CLAUDE_CODE_VIM` | ❌ | 启用 Vim 编辑模式 | `0` |

 ## 🔧 开发

@@ -308,11 +507,15 @@ java -jar target/claude-code-java-0.1.0-SNAPSHOT.jar
 | `cli.tsx` → `main.tsx` | `ClaudeCodeApplication` + `ClaudeCodeRunner` | 入口 |
 | `REPL.tsx` | `ReplSession` + JLine 3 | 交互循环 |
 | `query.ts` | `AgentLoop` | Agent 循环 |
-| `Tool.ts` + `tools/*` | `Tool` 接口 + `impl/*` | 工具系统 |
-| `commands.ts` | `SlashCommand` + `impl/*` | 命令系统 |
+| `Tool.ts` + `tools/*` | `Tool` 接口 + `impl/*` (18个) | 工具系统 |
+| `commands.ts` | `SlashCommand` + `impl/*` (28个) | 命令系统 |
 | `context.ts` + `prompts.ts` | `SystemPromptBuilder` + loaders | 上下文 |
 | `CLAUDE.md` + `skills/` | `ClaudeMdLoader` + `SkillLoader` | 记忆/技能 |
-| Ink Components | `console/*` 渲染器 | 终端 UI |
+| Ink Components | `console/*` 渲染器 (8个) | 终端 UI |
+| `mcp/*` (22文件) | `mcp/*` (McpClient/Manager/Transport) | MCP 协议 |
+| `plugins/*` (38文件) | `plugin/*` (Plugin/Manager/Context) | 插件系统 |
+| `hooks/*` | `HookManager` | Hook 系统 |
+| `tasks/*` | `TaskManager` + Task工具 | 任务管理 |

 ## 📄 License