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

17 KiB
Raw Blame History

需求进度追踪 - 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. 里程碑与进度

  • 阶段 1（需求澄清）：完成
  • 阶段 2（影响分析）：完成
  • 阶段 3（方案设计）：完成（已形成正式设计文档）
  • 阶段 4（实施计划）：完成（已形成正式实施计划）
  • 阶段 5（实现与自检）：完成（Task 1 至 Task 7 已完成，代码与构建回归通过）
  • 阶段 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