jadx-mcp-multisession: Instructions file for Codex

AGENTS.md — jadx-mcp-multisession 项目文档

给后来者（人 or AI）的速览：先读本文，再动手。完整功能说明见 README.md， 多会话改造与实测问题修复的详细记录见 MULTI_SESSION.md。

---

1. 项目是什么

Kimi Code / 任意 MCP 客户端与 jadx-gui 之间的桥接 server。上游是 zinja-coder/jadx-mcp-server v3.3.5，本项目在其上做了三件事：

1. 多会话管理：AI 可自主启动/切换/关闭多个 jadx-gui 窗口（对齐 IDA-MCP）
2. 插件版本兼容：jadx-ai-mcp 插件 3.3.x 与 6.x 参数名/端点差异自动适配
3. 错误降级：main-activity、strings 在上游插件失败时的 server 侧兜底

架构一句话：每个 jadx-gui 窗口 = 一个独立 HTTP 服务（插件端口）+ 独立 JADX_CONFIG_DIR/user.home；server 维护会话注册表，所有分析工具请求 路由到 active 会话。

2. 关键设计决策（改代码前必读）

2.1 多实例端口隔离 — FilePrefsFactory

jadx-ai-mcp 插件把端口存在 Java Preferences（Windows 注册表），所有实例 共享且无运行时改端口 API。解法：session-prefs-factory（Java）把 Preferences 落到文件。Windows JDK 没有 FileSystemPreferencesFactory，必须用这个自定义 实现（已实测 ClassNotFoundException）。

⚠️ 双节点预写：插件版本不同，Preferences 节点路径不同：

• 3.3.x → 包 jadx.gui.plugins → 文件 <prefs>/jadx/gui/plugins.properties
• 6.x → 包 com.zin.jadxaimcp → 文件 <prefs>/com/zin/jadxaimcp.properties

session_manager.open_session 必须两个都写，漏一个会导致对应版本插件 读默认 8650 → 多实例端口冲突 → 启动失败（已踩坑，勿回退）。

2.2 路由 — 单一改造点

所有分析工具最终都走 src/server/config.py 的 get_from_jadx()。

• current_base() 返回 active 会话 URL，无会话时回退旧 JADX_HTTP_BASE
• set_active_session() 切换会话时必须重置参数风格缓存（_PARAM_STYLE=None）
• 新工具若直接构造 URL 而不走 get_from_jadx，将不跟随会话切换（已踩坑）

2.3 参数风格自适应

插件参数名矩阵（实测确认）：

端点	3.3.x	6.3.0	6.4.0
class-source / methods-of-class 等	class	class_name	class_name
search-method	method	method_name	method_name
get-resource-file	name	file_name	file_name

• _detect_param_style()：向 /class-source?class_name=x.Y 发探测请求，400 且 报 "Missing 'class'" → legacy（3.3.x），否则 new
• _adapt_params()：legacy 时按 _LEGACY_RENAME 映射（class_name→class 等）
• dropins 插件默认选版本号最高的 jar（_find_plugin_jar 用 max 版本解析）， 3.3.x 缺 search-classes-by-keyword / xrefs-* / rename-package / debug 端点

2.4 会话生命周期

• 注册表：<sessions-dir>/sessions.json（含 active 指针），全部经 _mutate_registry 加锁读-改-写
• 启动：建目录 → 双节点预写端口 → 复制插件 jar 到 config/plugins/dropins/ （jadx 无条件加载机制，无需 plugins.json）→ jre/bin/java.exe 带 -Djava.util.prefs.PreferencesFactory / -Dfile.prefs.root / -Duser.home → 等 /health（150s）→ 等 /all-classes total>0（180s，大 APK 首次反编译） → 能力探测 probe_plugin() → 注册
• 关闭：taskkill /F /T /PID → 删注册 → active 自动转移 → 清理目录