GithubBackup/MyGoNavi
1
0
Fork 0
mirror of https://github.com/Syngnat/GoNavi.git synced 2026-05-06 20:03:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
6f14e827abbd48c960afe7c1a29aa1ce6242dc68
MyGoNavi/docs/需求追踪/需求进度追踪-JVM缓存可视化编辑-20260422.md
Syngnat 6f14e827ab ✨ feat(jvm): 完成资源治理与诊断增强 
- 新增 JMX/Endpoint/Agent 三种 JVM 连接模式与配置归一化链路
- 支持资源浏览、变更预览、写入应用、审计记录与只读约束
- 接入 AI 结构化写入计划与诊断计划回填能力
- 新增 Agent Bridge、Arthas Tunnel、JMX Helper 诊断传输实现
- 增加诊断控制台、命令模板、输出历史与自动补全交互
- 补齐前后端契约、运行夹具与 JVM 相关回归测试
2026-04-24 16:45:34 +08:00

247 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 需求进度追踪 - JVM缓存可视化编辑
## 1. 需求摘要
- 需求名称：JVM缓存可视化编辑
- 提出日期：2026-04-22
- 负责人：Codex
- 目标：完成 GoNavi 连接 Java JVM、可视化查看并修改 JVM 内缓存/对象值的通用能力交付，降低“改缓存只能写接口或重启应用”的运维与排障成本
- 非目标：不承诺覆盖所有 Java 框架/所有对象类型，不绕过目标应用现有安全控制，不在首期开放脚本式任意表达式执行
## 2. 范围与验收
- 范围：
- 交付 JVM 共享契约、连接配置、provider 注册、连接测试与能力探测
- 交付 Endpoint / JMX / Agent 三种接入模式及其资源浏览、读值、预览、执行链路
- 交付 JVM 资源页、预览弹窗、审计查看、AI 草稿生成与回填能力
- 交付 Guard、审计、来源标记、真实集成测试与构建验证
- 验收标准：
- 可以在 GoNavi 中新增 JVM 连接并完成连接测试
- 可以按资源树浏览 JVM 对象并查看结构化快照
- 可以对支持写入的资源执行预览和确认写入，且带 Guard 与审计
- 可以通过 AI 生成结构化修改草稿，但不会跳过人工确认直接执行
- 可以通过真实 JMX 与真实 HTTP contract 完成端到端验证，并通过前后端构建回归
- 依赖与约束：
- 需复用 GoNavi 当前 Wails + React + driver-agent 架构
- 新能力不得破坏现有数据库/Redis 工作流
- 高风险写操作必须具备明确鉴权、审计与回滚思路
- JMX 模式要求 GoNavi 运行机器本地可用 `java` 可执行文件
## 3. 里程碑与进度
- [x] 阶段 1（需求澄清）：完成
- [x] 阶段 2（影响分析）：完成
- [x] 阶段 3（方案设计）：完成（已形成正式设计文档）
- [x] 阶段 4（实施计划）：完成（已形成正式实施计划）
- [x] 阶段 5（实现与自检）：完成（Task 1 至 Task 7 已完成，代码与构建回归通过）
- [x] 阶段 6（评审与交付）：完成（已完成契约复核、上下文隔离修正、文档回填与交付检查）
- [ ] 阶段 7（发布与观察）：未开始
## 4. 变更清单
- 已完成：
- 确认 GoNavi 当前存在统一驱动接口与可选 driver-agent 机制
- 确认前端已有 Redis 结构化浏览、命令编辑器、Monaco 编辑器、DataGrid 编辑能力可复用
- 初步判断 JVM 运行时对象编辑不适合直接复用 SQL/Database 抽象，需新增非数据库协议层
- 用户已确认目标方向为“通用型 JVM 接入”
- 用户已确认升级到完整模式，开始高风险架构评估
- 用户明确目标 Java 服务大概率不允许 `-javaagent` 或运行时动态 attach
- 已形成 JVM 缓存可视化编辑正式设计文档
- 已形成 JVM Connector MVP 正式实施计划文档
- 已完成 Task 1：JVM 共享契约与配置归一化
- 已完成 Task 2：Provider 注册、连接测试与能力探测 API
- 已完成 Task 3：JVM 连接表单、图标与展示文案接入
- 已完成 Task 4：只读资源浏览与 JVM Tab
- 已完成 Task 5：写入预览、Guard 和审计记录
- 已完成 Task 6：AI 结构化变更计划
- 已完成 Task 7：全量回归、文档回填与交付检查
- 已完成 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 能力探测遵循只读配置，概览页能力矩阵补齐模式能力探测与多行错误展示，能力探测失败与风险/结果状态文案统一收口为中文业务语义
- 待处理：
- 无阻塞性交付项；后续仅保留复杂对象参数、`CompositeData` / `TabularData` 等高级类型写入扩展作为增强项
## 5. 风险与阻塞
- 风险：
- 直接修改 JVM 内对象属于高风险运行时操作，误改可能造成业务状态污染
- 不同缓存框架（Caffeine/Ehcache/Guava/自研 Map）缺少统一标准协议
- 若依赖 attach agent 或表达式执行，需严格控制安全边界与可观测性
- 若目标 JVM 不允许预埋或动态注入 Agent，则“通用型”能力边界会明显收缩
- 多接入模式会带来能力不一致问题，UI 与权限模型必须显式展示“当前模式支持什么/不支持什么”
- 当前 AI 能力边界仍是“分析 + 生成结构化计划 + 回填预览草稿”，不直接执行 JVM 写入，真实执行仍取决于 Guard、人工确认和 provider 能力
- 当前 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 资源页重新生成计划
- 阻塞：
- 当前开发收口阶段无新增阻塞
- 缓解措施：
- 优先收敛到标准接入面（JMX / Spring Actuator / Java Agent 三选一）
- 首期只支持白名单对象类型与受控写操作
- 要求变更审计、预览、确认与失败回滚路径
- 在交付说明中明确“AI 只生成草稿，不直接执行 JVM 写入”
- JMX helper 改为内嵌 runtime jar，默认写入用户缓存目录；必要时允许通过 `GONAVI_JMX_HELPER_CLASSPATH` 覆盖 classpath
- 对复杂参数调用保持白名单和人工确认，不开放脚本式自由执行
## 6. 决策记录
- 决策 1：先做可行性评估与方案设计，不直接进入实现
- 决策 2：默认优先复用 GoNavi 现有 driver-agent 与前端编辑器能力，避免侵入式重构主流程
- 决策 3：已按完整模式推进，后续方案将优先评估通用 Agent 路径是否成立
- 决策 4：由于目标服务大概率不允许 agent/attach，后续推荐方向转为“多接入模式 + 能力协商”
- 决策 5：AI 在 JVM 场景中只负责分析与生成结构化计划，不直接执行运行时写入
- 决策 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. 验证记录
- 验证项：
- GoNavi 驱动代理机制核查
- GoNavi 现有 Redis/编辑器/UI 复用能力核查
- JVM Connector 正式设计文档自检
- JVM Connector 实施计划文档自检
- 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：前端生产构建
- Task 7：Wails 生产构建
- 结果：
- 已确认存在可复用的连接桥接与编辑器基础设施
- 已完成正式设计文档落盘与自检，未发现占位词和明显范围冲突
- 已完成正式实施计划落盘与自检，已补齐共享 DTO、provider factory 和审计落盘等关键实现细节
- 已完成 JVM 连接共享契约、默认只读/默认 JMX 归一化、前端配置收敛与补测
- Task 1 已完成规格审查与代码质量审查，结论均通过
- 已完成 JVM Provider 工厂、JMX/Endpoint provider 骨架、App 层连接测试与能力探测 API
- Task 2 已完成规格审查与代码质量审查，结论均通过
- 已完成 JVM 连接类型卡片、最小表单字段、连接测试分发与展示文案接入
- Task 3 已完成规格审查与代码质量审查；过程中修复了 JVM 标题文案偏差、模式选项暴露范围、编辑态模式静默降级和 endpoint timeout 失真问题
- 已完成 JVM 只读资源浏览链路：后端新增 `JVMListResources` / `JVMGetValue`，前端新增 `jvm-overview` / `jvm-resource` tab 与侧边栏 JVM 模式/资源节点
- Task 4 已完成规格复审；代码质量复审确认真实 provider 浏览能力仍为后续任务范围，另外已修正 JVM 资源 tab 同名问题
- 已完成 Task 5：后端新增 `JVMPreviewChange` / `JVMApplyChange` / `JVMListAuditRecords`，补齐 Guard、审计 JSONL 落盘与审计读取能力
- Task 5 已补齐只读拦截、`prod` 环境确认、provider preview 错误透出、审计写入失败显式回传、连接 `allowedModes` 约束和局部快照合并保底
- 前端已完成 JVM 变更草稿区、预览弹窗、执行确认、审计记录页签与按 provider mode 的审计过滤
- 已完成 Task 6：AI 计划解析、资源定位解析、`updateValue -> put` 显式映射、JSON 对象 payload 约束和上下文绑定单测
- 已完成 Task 6：AI 聊天消息与 JVM 来源页签绑定，AI 气泡应用按钮不再依赖点击时的 `activeTabId`，避免跨 JVM 页签误投递
- 已完成 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，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`
- `frontend/src/components/RedisViewer.tsx`
- `frontend/src/components/RedisCommandEditor.tsx`
- `frontend/src/components/QueryEditor.tsx`
- `docs/superpowers/specs/2026-04-22-jvm-cache-visual-editing-design.md`
- `docs/superpowers/plans/2026-04-22-jvm-connector-mvp.md`
- `internal/connection/types.go`
- `internal/jvm/types.go`
- `internal/jvm/config.go`
- `internal/jvm/config_test.go`
- `frontend/src/types.ts`
- `frontend/src/utils/jvmConnectionConfig.ts`
- `frontend/src/utils/jvmConnectionConfig.test.ts`
- `go test ./internal/jvm -count=1`
- `go test ./...`
- `cd frontend && npm test -- src/utils/jvmConnectionConfig.test.ts`
- `cd frontend && npm test -- --run`
- `cd frontend && npm run build`
- `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`
- `frontend/wailsjs/go/app/App.js`
- `frontend/wailsjs/go/models.ts`
- `go test ./internal/app -run 'Test(TestJVMConnection|JVMProbeCapabilities)' -count=1`
- `go test ./internal/jvm ./internal/app -count=1`
- `wails build -clean`
- `frontend/src/components/DatabaseIcons.tsx`
- `frontend/src/components/ConnectionModal.tsx`
- `frontend/src/utils/jvmRuntimePresentation.ts`
- `frontend/src/utils/jvmRuntimePresentation.test.ts`
- `frontend/src/utils/jvmConnectionConfig.ts`
- `frontend/src/utils/jvmConnectionConfig.test.ts`
- `cd frontend && npm test -- src/utils/jvmRuntimePresentation.test.ts`
- `cd frontend && npm test -- src/utils/jvmConnectionConfig.test.ts`
- `cd frontend && npm run build`
- `internal/app/methods_jvm.go`
- `internal/app/methods_jvm_test.go`
- `frontend/src/components/Sidebar.tsx`
- `frontend/src/components/TabManager.tsx`
- `frontend/src/components/JVMOverview.tsx`
- `frontend/src/components/JVMResourceBrowser.tsx`
- `frontend/src/components/jvm/JVMModeBadge.tsx`
- `frontend/src/store.ts`
- `frontend/src/types.ts`
- `go test ./internal/app -run 'TestJVM(ListResources|GetValue)' -count=1`
- `go test ./internal/app -run 'TestJVMProbeCapabilities|TestTestJVMConnection' -count=1`
- `cd frontend && npm test -- src/utils/jvmRuntimePresentation.test.ts`
- `cd frontend && npm run build`
- `internal/jvm/guard.go`
- `internal/jvm/guard_test.go`
- `internal/jvm/audit_store.go`
- `internal/jvm/audit_store_test.go`
- `internal/app/methods_jvm.go`
- `internal/app/methods_jvm_test.go`
- `frontend/src/components/JVMAuditViewer.tsx`
- `frontend/src/components/jvm/JVMChangePreviewModal.tsx`
- `go test ./internal/jvm ./internal/app -run 'TestPreviewChangeBlocksReadOnlyConnection|TestPreviewChangeReturnsProviderPreviewErrorWhenWriteAllowed|TestPreviewChangeMarksProdWritesAsConfirmationRequired|TestPreviewChangeMergesProviderSnapshotsWithoutDroppingDefaults|TestJVMApplyChangeReturnsProviderPayload|TestJVMPreviewChangeRejectsModeOutsideAllowedModes|TestJVMListAuditRecordsReturnsLatestRecords|TestJVMApplyChangeSurfacesAuditWriteFailure' -count=1`
- `go test ./internal/jvm ./internal/app -count=1`
- `cd frontend && npm run build`
- `frontend/src/utils/jvmAiPlan.ts`
- `frontend/src/utils/jvmAiPlan.test.ts`
- `frontend/src/components/AIChatPanel.tsx`
- `frontend/src/components/ai/AIMessageBubble.tsx`
- `frontend/src/components/JVMResourceBrowser.tsx`
- `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. 下一步
- 下一步行动：由用户按真实 JVM / endpoint 场景执行验收验证；若验收通过，再决定是否提交、推送或继续扩展高级类型写入
- 负责人：Codex
Reference in New Issue View Git Blame Copy Permalink