✨ feat(jvm): 完成资源治理与诊断增强

- 新增 JMX/Endpoint/Agent 三种 JVM 连接模式与配置归一化链路
- 支持资源浏览、变更预览、写入应用、审计记录与只读约束
- 接入 AI 结构化写入计划与诊断计划回填能力
- 新增 Agent Bridge、Arthas Tunnel、JMX Helper 诊断传输实现
- 增加诊断控制台、命令模板、输出历史与自动补全交互
- 补齐前后端契约、运行夹具与 JVM 相关回归测试

docs/superpowers/specs/2026-04-22-jvm-cache-visual-editing-design.md

@@ -33,7 +33,7 @@ GoNavi 现有已具备三类可复用基础：
 - 不承诺“任意 JVM 内任意对象均可直接读写”
 - 不在首期支持任意 Java 表达式执行、任意反射路径写值或任意 classloader 深度探测
 - 不把 JVM 功能强行塞进现有 SQL `Database` / driver-agent 抽象
-- 不在首期承诺通过 Agent 模式支持所有缓存框架
+- 不承诺通过 Agent 模式支持所有缓存框架或任意深层对象写入
 - 不绕过目标服务现有认证、鉴权和网络边界
 
 ## 4. 需求与约束
@@ -102,12 +102,11 @@ JVM 缓存可视化编辑应当比照 Redis 独立建模，新增 `JVM Connector
 
 ## 7. 选型
 
-采用方案 B，首期 MVP 聚焦：
+采用方案 B。当前已落地：
 
 - `JMX Provider`
 - `Management Endpoint Provider`
-
-`Agent Provider` 只保留扩展位与接口约束，不纳入首期交付承诺。
+- `Agent Provider`（高级可选模式，要求目标 Java 服务显式预埋 GoNavi Java Agent）
 
 ## 8. 目标架构
 
@@ -169,11 +168,12 @@ JVM 缓存可视化编辑应当比照 Redis 独立建模，新增 `JVM Connector
 ### 9.3 Agent Provider
 
 - 负责：
-  - 在特定环境下提供更深层的运行时对象探测与写入能力
+  - 在特定环境下通过 GoNavi Java Agent 暴露受控管理端口
+  - 提供比 JMX 更贴近缓存资源模型的结构化浏览、预览与写入能力
 - 定位：
   - 高级模式
   - 不默认启用
-  - 不在首期交付
+  - 需要目标 Java 服务以 `-javaagent` 方式显式启动
 
 ## 10. 统一资源模型
 
@@ -283,7 +283,7 @@ AI 不直接输出脚本，而输出结构化变更计划，例如：
 
 - `JMX`
 - `Endpoint`
-- `Agent(禁用)`
+- `Agent`
 - `只读`
 - `可写`
 
@@ -415,10 +415,10 @@ JVM 审计日志不应复用 SQL 日志数据结构，但可以复用现有 LogP
 - AI 回滚建议
 - 仍默认不允许 AI 自动执行
 
-### Phase 4：高级模式预留
+### Phase 4：高级模式
 
-- Agent Provider SPI
-- 更深层 runtime 能力
+- Agent Provider
+- 预埋 Java Agent 的 runtime 资源治理能力
 - 仅在特殊环境启用
 
 ## 16. 验证策略
@@ -476,7 +476,7 @@ JVM 缓存可视化编辑能力在 GoNavi 中具备落地基础，但必须采
 
 - 新增独立的 `JVM Connector` 子系统
 - 首期支持 `JMX + Management Endpoint`
-- `Agent` 仅保留扩展位
+- `Agent` 作为高级可选模式交付
 - AI 首期支持分析与生成修改计划，不默认开放自动执行
 - 所有修改必须经过预览、确认、审计和回读验证
 

docs/需求追踪/需求进度追踪-JVM缓存可视化编辑-20260422.md

@@ -4,22 +4,26 @@
 - 需求名称：JVM缓存可视化编辑
 - 提出日期：2026-04-22
 - 负责人：Codex
-- 目标：评估并设计 GoNavi 连接 Java JVM、可视化查看并修改 JVM 内缓存/对象值的能力，降低“改缓存只能写接口或重启应用”的运维与排障成本
-- 非目标：不直接承诺覆盖所有 Java 框架/所有对象类型，不在需求未澄清前进入实现，不绕过目标应用现有安全控制
+- 目标：完成 GoNavi 连接 Java JVM、可视化查看并修改 JVM 内缓存/对象值的通用能力交付，降低“改缓存只能写接口或重启应用”的运维与排障成本
+- 非目标：不承诺覆盖所有 Java 框架/所有对象类型，不绕过目标应用现有安全控制，不在首期开放脚本式任意表达式执行
 
 ## 2. 范围与验收
 - 范围：
-  - 评估 GoNavi 现有驱动代理模型是否可扩展到 JVM 运行时连接
-  - 明确 JVM 缓存可视化编辑的接入方式、权限边界与最小可行产品范围
-  - 输出推荐方案、关键风险与后续实施方向
+  - 交付 JVM 共享契约、连接配置、provider 注册、连接测试与能力探测
+  - 交付 Endpoint / JMX / Agent 三种接入模式及其资源浏览、读值、预览、执行链路
+  - 交付 JVM 资源页、预览弹窗、审计查看、AI 草稿生成与回填能力
+  - 交付 Guard、审计、来源标记、真实集成测试与构建验证
 - 验收标准：
-  - 明确该需求在 GoNavi 内“能不能做”
-  - 明确推荐接入模式、前后端分层与安全边界
-  - 明确首期建议支持的缓存类型/Java 技术栈范围
+  - 可以在 GoNavi 中新增 JVM 连接并完成连接测试
+  - 可以按资源树浏览 JVM 对象并查看结构化快照
+  - 可以对支持写入的资源执行预览和确认写入，且带 Guard 与审计
+  - 可以通过 AI 生成结构化修改草稿，但不会跳过人工确认直接执行
+  - 可以通过真实 JMX 与真实 HTTP contract 完成端到端验证，并通过前后端构建回归
 - 依赖与约束：
   - 需复用 GoNavi 当前 Wails + React + driver-agent 架构
   - 新能力不得破坏现有数据库/Redis 工作流
   - 高风险写操作必须具备明确鉴权、审计与回滚思路
+  - JMX 模式要求 GoNavi 运行机器本地可用 `java` 可执行文件
 
 ## 3. 里程碑与进度
 - [x] 阶段 1（需求澄清）：完成
@@ -50,9 +54,17 @@
   - 已完成 JVM AI 计划解析、资源定位解析、AI 计划到当前 JVM 变更草稿的显式映射，避免把 `payload.format/value` 包装层直接透传到现有 JVM 写入契约
   - 已完成 AI 聊天面板 JVM 上下文注入、AI 气泡“应用到 JVM 预览”入口以及 JVM 资源页草稿回填闭环
   - 已完成 JVM AI 计划来源上下文绑定：消息现在绑定生成时的 `tabId + connectionId + providerMode + resourcePath`，避免切换 JVM 页签后误投递到当前激活页
+  - 已完成 Endpoint provider 真实 HTTP contract 与补测，支持资源浏览、读值、预览和执行
+  - 已完成可手工启动的 Java Endpoint fixture 与真实集成补测，可直接验证 Endpoint 模式端到端行为
+  - 已完成 JMX provider 真实 helper 接入与补测，支持 `domain -> mbean -> attribute/operation` 浏览、attribute `set`、operation `invoke`
+  - 已完成 JMX helper 预编译 runtime jar 内嵌分发，运行时不再依赖仓库源码目录，也不再要求本地 `javac`
+  - 已完成 JVM 快照动作提示与 payload 模板回填，前端可直接根据 `supportedActions` 生成草稿
+  - 已完成 AI 参与来源写入 JVM 审计记录，审计页可区分“手工”与“AI 辅助”
+  - 已完成 Agent provider、Agent 连接表单与概览展示，支持通过独立 Agent Base URL 接入 GoNavi Java Agent
+  - 已完成真实 Java Agent fixture 与集成验证，可通过 `-javaagent` 方式真实验证 Agent 模式资源浏览、预览与执行
+  - 已完成 JVM 收口优化：Endpoint 能力探测遵循只读配置，概览页能力矩阵补齐模式能力探测与多行错误展示，能力探测失败与风险/结果状态文案统一收口为中文业务语义
 - 待处理：
-  - 真实 provider 的 `PreviewChange` / `ApplyChange` 端到端能力验证
-  - AI 参与信息写入 JVM 审计记录
+  - 无阻塞性交付项；后续仅保留复杂对象参数、`CompositeData` / `TabularData` 等高级类型写入扩展作为增强项
 
 ## 5. 风险与阻塞
 - 风险：
@@ -61,12 +73,12 @@
   - 若依赖 attach agent 或表达式执行，需严格控制安全边界与可观测性
   - 若目标 JVM 不允许预埋或动态注入 Agent，则“通用型”能力边界会明显收缩
   - 多接入模式会带来能力不一致问题，UI 与权限模型必须显式展示“当前模式支持什么/不支持什么”
-  - 当前 JMX / Endpoint provider 的资源浏览与值读取仍是骨架实现，Task 4 已打通接口与 UI 链路，但真实资源展开会返回 `not implemented`
-  - Task 5 已打通 Guard/Preview/Audit 主链路，但真实 provider 的 `PreviewChange` / `ApplyChange` 能力仍依赖后续 provider 细化实现
   - 当前 AI 能力边界仍是“分析 + 生成结构化计划 + 回填预览草稿”，不直接执行 JVM 写入，真实执行仍取决于 Guard、人工确认和 provider 能力
-  - 当前 MVP 中 `updateValue` 会映射为现有 JVM 变更 contract 的 `put`，且 payload 仅接受 JSON 对象；非对象值、复杂二进制值和 provider 专有写法不在本期承诺范围
-  - AI 计划若只提供 `namespace + key`，当前仅按 `namespace/key` 推导资源 ID，属于 MVP 级资源定位约定，未承诺适配所有 provider 的资源 ID 规则
-  - JVM 审计记录当前未显式记录“AI 是否参与”，与理想审计模型仍有差距
+  - 当前 AI 计划若只提供 `namespace + key`，仍更适合 endpoint/cache 风格资源；JMX 复杂 target 仍建议优先使用 `resourcePath`
+  - JMX helper 已改为内嵌 jar 分发，但操作者机器仍需本地存在可用 `java`
+  - Agent 模式要求目标 Java 服务显式以 `-javaagent` 方式启动 GoNavi Java Agent，并额外暴露管理端口
+  - JMX operation preview 仅做参数/签名校验和预览快照，不预测真实副作用
+  - JMX 参数转换当前覆盖基础类型、`ObjectName` 和部分数组；复杂对象写入仍是后续扩展项
   - 历史旧 AI 消息不包含 JVM 来源上下文，若需要应用到预览，需在目标 JVM 资源页重新生成计划
 - 阻塞：
   - 当前开发收口阶段无新增阻塞
@@ -74,8 +86,9 @@
   - 优先收敛到标准接入面（JMX / Spring Actuator / Java Agent 三选一）
   - 首期只支持白名单对象类型与受控写操作
   - 要求变更审计、预览、确认与失败回滚路径
-  - 在交付说明中明确“AI 只生成草稿，不代表 provider 已具备真实写能力”
-  - 后续如进入真实接入阶段，优先补齐 provider 端到端验证与 AI 审计字段
+  - 在交付说明中明确“AI 只生成草稿，不直接执行 JVM 写入”
+  - JMX helper 改为内嵌 runtime jar，默认写入用户缓存目录；必要时允许通过 `GONAVI_JMX_HELPER_CLASSPATH` 覆盖 classpath
+  - 对复杂参数调用保持白名单和人工确认，不开放脚本式自由执行
 
 ## 6. 决策记录
 - 决策 1：先做可行性评估与方案设计，不直接进入实现
@@ -86,6 +99,8 @@
 - 决策 6：AI 计划应用入口只回填 JVM 预览草稿，后续仍必须经过 `JVMPreviewChange`、Guard 校验和人工确认
 - 决策 7：当前 MVP 中 `updateValue` 会映射到现有 JVM 变更 contract 的 `put`，且 payload 仅接受 JSON 对象
 - 决策 8：JVM AI 计划必须绑定生成时的 JVM 上下文，只允许投递到匹配的 `tabId + connectionId + providerMode + resourcePath`
+- 决策 9：JMX helper 采用 Java 8 兼容的预编译 runtime jar 内嵌分发，运行时只依赖本地 `java`
+- 决策 10：Agent 模式按“预埋 GoNavi Java Agent + 独立 Agent Base URL 接入”落地，不在当前版本实现动态 attach
 
 ## 7. 验证记录
 - 验证项：
@@ -96,6 +111,9 @@
   - Task 1：JVM 共享契约与配置归一化
   - Task 2：Provider 注册、连接测试与能力探测 API
   - Task 6：AI 计划解析、资源定位解析、契约映射与页签上下文隔离
+  - Task 7：Java Endpoint fixture 真实集成验证
+  - Task 7：JMX helper 内嵌分发与运行时缓存验证
+  - Task 7：Agent provider 与真实 Java Agent 集成验证
   - Task 7：后端全量测试
   - Task 7：前端全量测试
   - Task 7：前端生产构建
@@ -117,11 +135,24 @@
   - 前端已完成 JVM 变更草稿区、预览弹窗、执行确认、审计记录页签与按 provider mode 的审计过滤
   - 已完成 Task 6：AI 计划解析、资源定位解析、`updateValue -> put` 显式映射、JSON 对象 payload 约束和上下文绑定单测
   - 已完成 Task 6：AI 聊天消息与 JVM 来源页签绑定，AI 气泡应用按钮不再依赖点击时的 `activeTabId`，避免跨 JVM 页签误投递
-  - `cd frontend && npm test -- --run src/utils/jvmAiPlan.test.ts` 通过（10 tests）
+  - 已完成 Task 7：Java Endpoint fixture，可真实验证 `resources / value / preview / apply` 四个 endpoint contract
+  - `go test ./internal/jvm -run 'TestHTTPProvider' -count=1` 通过
+  - 已完成 Task 7：JMX helper 改为预编译 jar 内嵌分发，并补齐 classpath 覆盖与缓存落盘单测
+  - `go test ./internal/jvm -run 'TestEnsureJMXHelperRuntime|TestJMXProvider' -count=1` 通过
+  - 已完成 Task 7：Agent provider、Java agent fixture 与真实 `-javaagent` 集成测试
+  - `go test ./internal/jvm -run 'TestAgentProvider' -count=1` 通过
+  - `cd frontend && npm test -- --run src/utils/jvmAiPlan.test.ts` 通过（11 tests）
   - `go test ./... -count=1` 通过
-  - `cd frontend && npm test -- --run` 通过（61 files，258 tests）
+  - `cd frontend && npm test -- --run` 通过（61 files，259 tests）
   - `cd frontend && npm run build` 通过；构建中存在既有 chunk size / dynamic import 警告，但未阻塞产物生成
   - `wails build -clean` 通过，成功生成 macOS 应用包
+  - 已完成 JVM 收口优化：模式能力探测现在按当前 mode 做业务化错误翻译，避免概览页继续回显 `non-JRMP server`、`baseURL is required` 这类原始报错
+  - `go test ./internal/jvm -run 'TestHTTPProvider' -count=1` 再次通过（Endpoint 能力探测只读语义回归）
+  - `go test ./internal/app -run 'Test(TestJVMConnection|JVMProbeCapabilities)' -count=1` 再次通过（能力探测模式透传与中文错误翻译回归）
+  - `cd frontend && npm test -- --run src/components/JVMResourceBrowser.layout.test.tsx` 通过（JVM 资源页布局回归）
+  - `cd frontend && npm test -- --run src/utils/jvmResourcePresentation.test.ts` 通过（风险等级、审计结果等本地化展示回归）
+  - `cd frontend && npm run build` 再次通过
+  - `wails build -clean` 再次通过，成功生成最新可验收桌面包
 - 证据（日志/截图/链接）：
   - `cmd/optional-driver-agent/main.go`
   - `internal/db/database.go`
@@ -145,7 +176,15 @@
   - `internal/jvm/provider.go`
   - `internal/jvm/jmx_provider.go`
   - `internal/jvm/http_provider.go`
+  - `internal/jvm/http_provider_test.go`
+  - `internal/jvm/jmx_helper.go`
+  - `internal/jvm/jmx_helper_test.go`
   - `internal/jvm/provider_contract_test.go`
+  - `internal/jvm/jmxhelper_assets/jmx-helper-runtime.jar`
+  - `internal/jvm/jmxhelper_assets/README.md`
+  - `internal/jvm/testdata/endpointfixture/src/com/gonavi/fixture/EndpointTestServer.java`
+  - `internal/jvm/testdata/endpointfixture/src/com/gonavi/fixture/MiniJson.java`
+  - `tools/jmx-helper/src/com/gonavi/jmxhelper/JmxHelperMain.java`
   - `internal/app/methods_jvm.go`
   - `internal/app/methods_jvm_test.go`
   - `frontend/wailsjs/go/app/App.d.ts`
@@ -195,9 +234,13 @@
   - `frontend/src/types.ts`
   - `cd frontend && npm test -- --run src/utils/jvmAiPlan.test.ts`
   - `go test ./... -count=1`
+  - `go test ./internal/jvm -run 'TestHTTPProvider' -count=1`
+  - `go test ./internal/jvm -run 'TestEnsureJMXHelperRuntime|TestJMXProvider' -count=1`
+  - `cd frontend && npm test -- --run src/components/JVMResourceBrowser.layout.test.tsx`
+  - `cd frontend && npm test -- --run src/utils/jvmResourcePresentation.test.ts`
   - `cd frontend && npm test -- --run`
   - `wails build -clean`
 
 ## 8. 下一步
-- 下一步行动：如进入真实接入阶段，优先补齐 provider 端到端写入验证、AI 参与审计字段和生产环境灰度验证
+- 下一步行动：由用户按真实 JVM / endpoint 场景执行验收验证；若验收通过，再决定是否提交、推送或继续扩展高级类型写入
 - 负责人：Codex