# jdi-debugger

**Repository Path**: beiding/jdi-debugger

## Basic Information

- **Project Name**: jdi-debugger
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JDI Debugger

## 开发规范：错误判定与消息展示

- 禁止使用错误消息文本、关键字或正则表达式判断错误类型、业务状态或是否忽略错误；禁止通过消息内容（例如 `ok`、`timeout`、`invalid state`）屏蔽真实错误。
- 错误分支必须依据结构化响应字段判断，包括 HTTP 状态码、业务 `code`、明确的状态字段及错误对象属性。前端业务逻辑不得依赖 `error.message` 的语言、格式或文案。
- 公共消息组件只负责展示已经分类的错误，不得在 `toast`、消息格式化或通用错误映射中改变错误语义、吞掉异常或将不同错误合并成状态提示。
- 如果某种状态属于正常竞态，应在发起该业务请求的业务位置依据响应码/错误码处理，并执行必要的状态刷新；原始错误仍应可通过结构化字段和诊断日志追踪。

## 文档阅读顺序与职责

README 只提供项目入口、模块关系、启动方式和文档导航；具体规则以对应职责文档为准。开始开发或排查问题时，按以下顺序阅读：

1. [`docs/architecture/PROJECT_DESIGN.md`](docs/architecture/PROJECT_DESIGN.md)：确认项目定位、状态所有权、连接/Session 生命周期、事件顺序、前后端边界和设计验收约束。
2. [`docs/development/DEVELOPMENT_GUIDELINES.md`](docs/development/DEVELOPMENT_GUIDELINES.md)：执行编码、分层、依赖、DTO、错误处理、日志、资源释放、测试和提交规范；这是开发实现时的正式规范文件。
3. [`docs/architecture/PACKAGE_STRUCTURE.md`](docs/architecture/PACKAGE_STRUCTURE.md)：根据包职责选择代码位置，确认 Controller、Service、`core.port`、`core.internal`、RemoteAgent 和工具类之间的依赖方向。
4. [`docs/api/HTTP_API.md`](docs/api/HTTP_API.md)：修改或调用 HTTP/SSE 时，查阅请求参数、响应 envelope、HTTP 状态码、业务错误码、`pauseId`、事件序号和 SSE 重连约定。
5. 前端改动阅读 [`ui/README.md`](ui/README.md)；测试改动阅读 [`test/README.md`](test/README.md)，再按其中索引进入选择器、测试策略、测试用例和实施规范文档。

对应关系：

| 工作内容 | 正式依据 | 重点检查 |
|---|---|---|
| Java 后端、Core、Service、Controller | `docs/development/DEVELOPMENT_GUIDELINES.md` | 分层依赖、状态所有权、错误码、资源释放、测试与提交 |
| 整体架构或生命周期变更 | `docs/architecture/PROJECT_DESIGN.md` | 连接/Session、事件顺序、并发、持久化和前后端边界 |
| 包位置或模块依赖 | `docs/architecture/PACKAGE_STRUCTURE.md` | 代码应放在哪一层、允许依赖哪些接口 |
| HTTP/SSE 接口 | `docs/api/HTTP_API.md` | 响应码、业务 `code`、请求上下文、事件与重连 |
| 静态前端 | `ui/README.md`、`ui/docs/` | adapter、状态同步、稳定选择器、视觉验收 |
| 前端自动化测试 | `test/README.md`、`test/docs/` | 功能 ID、用例映射、等待/隔离/清理和失败证据 |

JDI Debugger 是一个面向开发、测试和故障诊断的远程 JVM 调试工作台。它通过 JDI/JDWP 连接目标 JVM，
通过 HTTP/SSE 向浏览器、AI 或其他 API 客户端提供统一的调试能力，并让人工用户实时观察和监管调试过程。

## 1. 提供的能力

- 连接配置、连接切换、Session 激活和断开；
- Java 源码工作区、源码树、类名索引、全局搜索和文件编辑；
- 行断点、方法断点、异常断点、字段观察点、事件断点、日志断点和条件断点；
- 暂停、继续、步入、步过、步出、运行到光标和严格状态冲突检查；
- 线程、调用栈、栈帧、局部变量、对象展开、Watch、表达式求值和变量写值；
- 本地源码优先、远程 class 获取和反编译回退；
- Automation 和 Script 的真实文件管理、编译、执行、运行期文件和授权控制；
- stdout/stderr/debug 控制台、源码 watcher、热替换和调试事件流；
- 多浏览器和无界面 API 客户端共享同一个活动 JDI Session；
- FLOW 全事件跟随、冻结视图和恢复最新共享快照；
- 连接级和全局授权策略、授权申请、人工批准/拒绝及授权历史。

项目的核心目的有两个：让 AI 能通过稳定 API 看见程序运行细节，让人工能在浏览器中观察并监管 AI 的
敏感调试操作，例如脚本执行、表达式求值、条件断点和变量写值。

## 2. 总体架构

```text
浏览器 / AI / 其他 API 客户端
             |
        HTTP / SSE
             |
        Controller
             |
       Service
       /     \\
  core.port  persistence.port
       |          |
 core.internal persistence.file
       |          |
       JDI    filesystem
             |
          目标 JVM
```

### Core

Core 是跨模块的 JDI 运行时和调试状态基础；Persistence 负责连接清单、当前激活连接、每个 connectionId
的独立工作区及全局/运行期存储。任意时刻只有一个活动连接和一个活动 JDI Session；多个客户端
观察的是同一个后端权威状态。

### 业务模块

| 模块 | 主要职责 |
|---|---|
| `connection` | 连接配置、connectionId、激活和连接列表清理 |
| `session` | JDI 会话生命周期、运行状态、断开原因和 Session 持久化 |
| `source` | 源码工作区、扫描、索引、watcher、冲突处理和源码定位 |
| `clazzes` | 已加载类、远程 class、反编译和 HotSwap |
| `breakpoint` | 断点定义、安装、命中、启停、恢复和清理 |
| `execution` | 暂停、继续、步进、运行到光标和状态冲突 |
| `inspection` | 线程、栈帧、变量、Watch、求值、写值和诊断快照 |
| `script` | 脚本编译、执行、直接运行和脚本授权 |
| `automation` | 自动化定义、编译、执行、直接运行和自动化授权 |
| `authorization` | 授权申请、批准/拒绝、会话级策略、全局策略和历史 |
| `remote` | RemoteAgent 注入、远程编译、输出捕获和目标 JVM 内能力 |

业务模块依赖 `core.port`，不能直接依赖 `core.internal` 或 HTTP 类型。详细包结构见
[`docs/architecture/PACKAGE_STRUCTURE.md`](docs/architecture/PACKAGE_STRUCTURE.md)。

## 3. 持久化布局

后端默认使用运行目录下的 `work/`：

```text
work/
├─ connections.json           连接清单和当前 activeConnectionId
├─ contexts/<connectionId>/   连接级模块数据
├─ global/authorization/      全局授权策略
└─ runtime/                   直接运行脚本、自动化和临时缓存
```

临时 Session 和临时源码阅读状态使用 `runtime` 存储；连接断开时由 Persistence 清理。连接配置本身只保存
连接所需信息，不把源码、断点、Watch、脚本或授权记录混进连接配置。

## 4. 构建和启动

### 4.1 环境要求

- Java 21（项目使用 records、模式匹配和虚拟线程等 Java 21 特性）；
- Maven 3.x；
- Node.js 仅用于前端契约和 Playwright 测试，不参与前端构建；
- 真实调试需要一个开启 JDWP 的目标 JVM；
- Automation、Script、控制台和热替换测试还需要 RemoteAgent。

项目使用 UTF-8 和 Java 21 编译目标，并依赖 `jdk.jdi`、`jdk.compiler` 模块。Windows 环境应确保
`JAVA_HOME` 指向 JDK 21。

### 4.2 构建

```powershell
mvn clean package
```

生成的 JAR 位于 `target/`。构建前应确认 `JAVA_HOME` 指向目标 JDK，并确保 `java`、`javac` 和 `mvn` 来自
同一套兼容环境。

### 4.3 启动后端

默认监听 `127.0.0.1:7777`：

```powershell
java -jar target/jdi-debugger-1.0.0-SNAPSHOT.jar
```

指定端口时把端口作为第一个参数：

```powershell
java -jar target/jdi-debugger-1.0.0-SNAPSHOT.jar 17777
```

启动后访问：

```text
http://127.0.0.1:7777/ui/index.html
```

服务仅监听本机回环地址，适合可信开发和测试环境，不是生产级公网服务部署方案。

## 5. HTTP 与 SSE

接口统一返回包含 `success`、`code`、`message`、`data`、`requestId` 和 `timestamp` 的响应外壳。HTTP 用于
查询快照和发起明确命令，SSE 用于推送连接、Session、源码、断点、执行、检查、授权和控制台事件。

常用接口类别：

- `/connections`：连接配置和激活；
- `/sessions`：Session 激活、状态和断开；
- `/source-workspaces`、`/sources`：源码工作区、树、文件和搜索；
- `/breakpoints`：断点定义和管理；
- `/execution/*`：暂停、继续、步进和运行到光标；
- `/inspection`：线程、栈帧、变量、Watch、求值和写值；
- `/diagnostics`：审计查询和受控诊断导出；
- `/scripts`、`/automation`：定义管理、编译和执行；
- `/authorization`：授权申请和审批；
- 统一 SSE 事件路径：`/events`；Session 控制台兼容流：`/session/console`（不再提供 `/console`）。

完整参数、错误码和事件格式见 [`docs/api/HTTP_API.md`](docs/api/HTTP_API.md)。接口面向 AI 和前端共同使用，优先保持参数
简洁，常规调试命令默认作用于 Core 当前活动上下文。敏感操作必须经过授权模块。

## 6. 前端使用

`ui/` 是无需构建的静态前端，包含 HTML、CSS、JavaScript、CodeMirror 和数据源 adapter。后端同源访问时
使用真实 HTTP/SSE adapter；独立静态打开页面时可以使用 Mock adapter 做离线视觉检查。真实联调不能使用
Mock adapter 代替后端行为。

前端主要区域：

- 顶部连接配置、Debug、断开、FLOW 和全局搜索；
- 左侧项目、Automation、Script、授权工具面板；
- 中央源码编辑器、标签和源码路径；
- 底部调试工具窗，包括调试、线程、框架、变量、Watch 和控制台；
- 右侧通知抽屉；
- 配置、求值、断点、授权和源码冲突弹窗。

静态前端说明见 [`ui/README.md`](ui/README.md)，稳定选择器见
[`ui/docs/TEST_SELECTORS.md`](ui/docs/TEST_SELECTORS.md)，视觉检查见
[`ui/docs/VISUAL_CHECKLIST.md`](ui/docs/VISUAL_CHECKLIST.md)。

## 7. 测试工程

根目录 `test/` 是独立的前端测试工程，采用有头 Playwright、Node.js 契约测试、真实 JDWP 目标和多客户端
场景。测试功能范围、架构、规范、设计、用例和实施状态分别见：

- [`test/README.md`](test/README.md)：测试工程入口和运行说明；
- [`test/docs/UI_TEST_FUNCTIONS.md`](test/docs/UI_TEST_FUNCTIONS.md)：115 个功能点；
- [`test/docs/TEST_CASES.md`](test/docs/TEST_CASES.md)：与功能点一一对应的可执行用例；
- [`test/docs/TEST_STRATEGY.md`](test/docs/TEST_STRATEGY.md)：测试架构、矩阵和套件设计；
- [`test/docs/TEST_GUIDELINES.md`](test/docs/TEST_GUIDELINES.md)：测试实施规范；
- [`test/TODO.md`](test/TODO.md)：自动化实施待办。

当前契约测试可以直接执行：

```powershell
node test/old/adapter-contract.test.js
node test/old/authorization-dialog-contract.test.js
node test/old/bootstrap-once.test.js
node test/old/configuration-editor.test.js
```

真实有头浏览器测试要求后端、JDWP 目标和环境变量准备完成，配置和命令见
[`test/playwright.config.js`](test/playwright.config.js) 与 [`test/README.md`](test/README.md)。

## 8. 开发约束与设计文档

开始修改代码前必须阅读并更新
[`docs/architecture/PROJECT_DESIGN.md`](docs/architecture/PROJECT_DESIGN.md)，再按
[`docs/development/DEVELOPMENT_GUIDELINES.md`](docs/development/DEVELOPMENT_GUIDELINES.md) 实施。重点约束包括：

- 模块单向依赖和清晰职责；
- Core 是 JDI 运行时和调试状态的唯一权威，Persistence 是连接与文件存储的唯一权威；
- 严格调试状态机，期望状态不匹配立即返回稳定错误；
- 所有 Java 源代码和文档使用 UTF-8；
- DTO、VO 和实体字段使用中文含义注释，Service/接口方法使用中文职责说明；
- 敏感操作必须经过授权；
- 修改后执行构建、相关测试、格式化检查和 `git diff --check`。

项目设计总览见 [`docs/architecture/PROJECT_DESIGN.md`](docs/architecture/PROJECT_DESIGN.md)，历史设计原则审计见
[`docs/archive/DESIGN_PRINCIPLES_AUDIT.md`](docs/archive/DESIGN_PRINCIPLES_AUDIT.md)。

## 9. 目录速查

| 目录/文件 | 用途 |
|---|---|
| `src/main/java` | Java 后端、业务模块、Controller、Core 和 RemoteAgent |
| `src/test/java` | Java 单元、验证器和真实 JDI/RemoteAgent 集成验证 |
| `ui` | 静态前端、adapter、样式、视觉素材和 CodeMirror |
| `test` | 前端契约、Playwright、测试架构、用例和测试待办 |
| `verification-target` | 用于真实 JDWP 验证的目标 JVM 工程 |
| `work` | Persistence 的连接级、全局和运行期存储；不应当提交运行数据 |
| `target` | Maven 构建产物；不应当提交 |
| `docs/architecture` | 项目设计、持久化和 Java 包结构 |
| `docs/api` | HTTP/SSE 接口和事件说明 |
| `docs/development` | 开发、编码、注释、测试和提交规范 |
| `docs/planning/TODO.md` | 当前未完成或待确认的项目事项 |
| `docs/archive` | 已完成台账、历史问题和审计记录 |

## 10. 设计边界

本项目是调试控制和观测后端，不是通用数据库、任务队列或生产级多租户平台。它默认运行在可信的本地开发
网络中，不默认提供公网认证、TLS、高可用切换或复杂租约协调。若未来任务明确要求这些能力，应先更新
项目设计和安全边界，再实施对应功能。