dsh-plugin-cfr 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# dsh-plugin-cfr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 `cfr` 与 `rg` 注册为 DSH 的模型工具，给 Agent 一套完整的 jar 反编译体验：反编译一次、全文检索、按类读取。
+
+cfr.jar 已随插件分发（`vendor/cfr.jar`，CFR 0.152，MIT 许可证），rg 由 `@vscode/ripgrep` 依赖提供，系统里只需要有 `java`。
+
+## 工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `jar_decompile` | 把整个 jar 反编译到缓存目录，返回目录与 Java 文件数。同一个 jar 只真正编译一次，之后直接命中缓存。 |
+| `jar_search` | 在反编译源码里用 ripgrep 做正则检索，返回 `文件:行号:内容`；jar 未反编译时自动先反编译。 |
+| `jar_read` | 按类名读取源码，支持全限定名、内部名与短名，按行返回并可用 `offset` / `limit` 翻页；缓存缺失时即时反编译单个类。 |
+
+会话工作目录用于解析相对路径，所以 `jar_read { jar: "lib/foo.jar", className: "Bar" }` 直接可用。
+
+## 缓存
+
+反编译结果按 jar 的路径与内容指纹落在 `$DSH_HOME/cache/jar-decompile/<jar 名>-<指纹>/`，跨会话、跨工作区复用。jar 内容变化会生成新目录，旧目录可随时删除。
+
+## 配置
+
+默认无需配置。要换 cfr 版本、调整缓存位置或换 ripgrep 时，在 profile 的 `cordis.patch.yml` 里覆盖 `jar-cfr` 行的 `config`：
+
+```yaml
+- id: jar-cfr
+  config:
+    cacheDir: D:\cache\jar-decompile
+    javaPath: java
+    cfrJar: D:\tools\cfr-0.152.jar
+    rgPath: ''
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `cacheDir` | `$DSH_HOME/cache/jar-decompile` | 反编译缓存根目录 |
+| `javaPath` | `java` | 启动 cfr 用的 java |
+| `cfrJar` | 内置 `vendor/cfr.jar` | 想换版本时给出 cfr.jar 的绝对路径 |
+| `rgPath` | 内置 `@vscode/ripgrep` | 想换 ripgrep 时给出可执行文件路径 |
+
+## 依赖
+
+- `java`：PATH 上可用，或用 `javaPath` 指定。
+- `rg`：由 `@vscode/ripgrep` 依赖提供；依赖缺失时回退到 PATH 上的 `rg`。
+- `cfr.jar`：已内置，无需单独安装。
+
+## 安装
+
+先在插件目录安装依赖：
+
+```
+pnpm install
+```
+
+再在 DSH 里用插件管理安装本目录的 bundle：
+
+```
+plugin_manager action=install_bundle target=<本目录绝对路径>
+```

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: jar-cfr
+      name: dsh-plugin-cfr
+      config:
+        cacheDir: ''
+        javaPath: java
+        cfrJar: ''
+        rgPath: ''

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Jar decompiler">
+  <rect width="64" height="64" rx="14" fill="#0b5cad"/>
+  <path d="M23 20h18l-2 30H25z" fill="#ffffff" opacity="0.96"/>
+  <rect x="20" y="15" width="24" height="7" rx="2" fill="#ffffff"/>
+  <path d="M28 30l-4 5 4 5M36 30l4 5-4 5" fill="none" stroke="#0b5cad" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -0,0 +1,25 @@
+/**
+ * Host 半入口：把 cfr 与 rg 注册为模型可调用的 jar 工具。
+ */
+
+import { createCfr } from './src/cfr.js'
+import { normalizeConfig } from './src/config.js'
+import { createRg } from './src/rg.js'
+import { registerJarTools } from './src/tools.js'
+
+/** Loader 条目标识，与 patch 里的 id 一致。 */
+export const name = 'jar-cfr'
+
+/** 硬依赖：缺工具注册表或子进程服务时插件不加载。 */
+export const inject = ['tools', 'subprocess']
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ cacheDir?: string, javaPath?: string, cfrJar?: string, rgPath?: string }} [config]
+ */
+export function apply(ctx, config = {}) {
+  const settings = normalizeConfig(config)
+  const cfr = createCfr(ctx, settings)
+  const rg = createRg(ctx, settings)
+  return ctx.effect(() => registerJarTools(ctx, { cfr, rg }))
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Jar decompiler",
+    "description": "Wraps cfr and ripgrep to decompile jars, search sources, and read classes."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Jar 反编译",
+    "description": "封装 cfr 与 rg，提供反编译、源码检索与按类读取三个工具。"
+  }
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "dsh-plugin-cfr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "把 cfr 与 rg 注册为 DSH 的 jar 反编译工具。",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "vendor",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@vscode/ripgrep": "^1.18.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/src/cfr.js

@@ -0,0 +1,256 @@
+/**
+ * cfr 调用层：解析 java 入口、维护反编译缓存、执行全量与单类反编译。
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+
+const GRACE_MS = 5000
+const COLLECT_BYTES = 64 * 1024
+const SPILL_BYTES = 1024 * 1024
+const SINGLE_CLASS_BYTES = 4 * 1024 * 1024
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ cacheDir: string, javaPath: string, cfrJar: string }} config
+ */
+export function createCfr(ctx, config) {
+  /** 每个缓存目录下已扫描出的 Java 源码路径。 */
+  const listings = new Map()
+  /** 同一 jar 的并发反编译只跑一次。 */
+  const inflight = new Map()
+  let javaExecutable
+
+  async function javaCommand(signal) {
+    if (!javaExecutable) {
+      javaExecutable = ctx.subprocess.resolveExecutable(config.javaPath, undefined, signal)
+    }
+    try {
+      return await javaExecutable
+    } catch (error) {
+      javaExecutable = undefined
+      throw error
+    }
+  }
+
+  /**
+   * cfr 的启动 argv：始终用 java 直接拉起 cfr.jar，不经过任何命令行包装。
+   * @param {readonly string[]} args
+   * @param {AbortSignal} [signal]
+   */
+  async function cfrArgv(args, signal) {
+    if (!config.cfrJar) {
+      throw new Error('没有配置 cfrJar：请在插件配置里给出 cfr.jar 的绝对路径。')
+    }
+    return [await javaCommand(signal), '-jar', config.cfrJar, ...args]
+  }
+
+  /**
+   * 运行一次子进程并回收输出；非零退出码属于正常返回。
+   */
+  async function run(argv, { cwd, signal, maxBytes = COLLECT_BYTES, spill = true }) {
+    const stdio = {
+      stdin: 'ignore',
+      stdout: { maxBytes, ...(spill ? { spill: { maxBytes: SPILL_BYTES } } : {}) },
+      stderr: { maxBytes, ...(spill ? { spill: { maxBytes: SPILL_BYTES } } : {}) },
+    }
+    const handle = ctx.subprocess.spawn({ argv, cwd, stdio, graceMs: GRACE_MS, signal })
+    const outcome = await handle.done
+    const stdout = readCollected(handle.collected.stdout)
+    const stderr = readCollected(handle.collected.stderr)
+    return {
+      exitCode: outcome.exitCode,
+      signal: outcome.signal ?? undefined,
+      stdout: stdout.text,
+      stderr: stderr.text,
+      truncated: stdout.lossy || stderr.lossy,
+      spillPath: stdout.spillPath ?? stderr.spillPath,
+    }
+  }
+
+  /**
+   * 反编译整个 jar 到缓存目录；已完成过的缓存直接复用。
+   * @param {string} jarPath 已解析的 jar 绝对路径
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<{ outDir: string, classCount: number, cached: boolean }>}
+   */
+  async function decompile(jarPath, signal) {
+    const jar = resolve(jarPath)
+    const info = await stat(jar)
+    if (!info.isFile()) throw new Error(`不是文件：${jar}`)
+    const dir = cacheDirectory(jar, info)
+    const outDir = join(dir, 'sources')
+    const marker = join(dir, 'done.json')
+    const done = await readMarker(marker)
+    if (done) return { outDir, classCount: done.classCount, cached: true }
+    const running = inflight.get(dir)
+    if (running) return running
+    const task = compile(jar, dir, outDir, marker, info, signal).finally(() => inflight.delete(dir))
+    inflight.set(dir, task)
+    return task
+  }
+
+  async function compile(jar, dir, outDir, marker, info, signal) {
+    await rm(dir, { recursive: true, force: true })
+    await mkdir(outDir, { recursive: true })
+    listings.delete(outDir)
+    const argv = await cfrArgv([jar, '--outputdir', outDir], signal)
+    const result = await run(argv, { cwd: dirname(jar), signal })
+    if (result.exitCode !== 0) {
+      throw new Error(`cfr 退出码 ${result.exitCode}：${tail(result.stderr || result.stdout)}`)
+    }
+    const classCount = (await listJavaFiles(outDir)).length
+    if (classCount === 0) {
+      throw new Error(`cfr 没有产出源码，输入可能不是 jar：${tail(result.stderr || result.stdout)}`)
+    }
+    const record = { jar, classCount, size: info.size, createdAt: new Date().toISOString() }
+    await writeFile(marker, JSON.stringify(record), 'utf8')
+    return { outDir, classCount, cached: false }
+  }
+
+  /**
+   * 读取一个类的源码：缓存优先，缺失时即时单类反编译并写入部分缓存。
+   * @param {string} jarPath jar 绝对路径
+   * @param {string} className 全限定名、内部名或短名
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<{ status: 'ok', source: string, path: string, cached: boolean }
+   *   | { status: 'ambiguous', candidates: string[] }
+   *   | { status: 'missing' }>}
+   */
+  async function readClass(jarPath, className, signal) {
+    const jar = resolve(jarPath)
+    const info = await stat(jar)
+    const dir = cacheDirectory(jar, info)
+    const found = await findClass(dir, className)
+    if (found) return found
+    const source = await decompileSingle(jar, className, signal)
+    if (source === undefined) return { status: 'missing' }
+    const relative = `${normalizeClassPath(className)}.java`
+    const target = join(dir, 'partial', ...relative.split('/'))
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, source, 'utf8')
+    listings.delete(join(dir, 'partial'))
+    return { status: 'ok', source, path: relative, cached: false }
+  }
+
+  /**
+   * 在缓存与部分缓存里查找一个类。
+   */
+  async function findClass(dir, className) {
+    const relative = normalizeClassPath(className)
+    if (!relative) return undefined
+    const target = `${relative}.java`
+    const roots = [join(dir, 'sources'), join(dir, 'partial')].filter((root) => existsSync(root))
+    for (const root of roots) {
+      if ((await listJavaFiles(root)).includes(target)) {
+        return { status: 'ok', source: await readFile(join(root, target), 'utf8'), path: target, cached: true }
+      }
+    }
+    const short = `${relative.split('/').pop().toLowerCase()}.java`
+    const named = []
+    const fuzzy = []
+    for (const root of roots) {
+      for (const file of await listJavaFiles(root)) {
+        const base = file.split('/').pop().toLowerCase()
+        if (base === short) named.push({ root, file })
+        else if (base.includes(short.replace(/\.java$/u, ''))) fuzzy.push({ root, file })
+      }
+    }
+    const pool = named.length > 0 ? named : fuzzy
+    if (pool.length === 1) {
+      const [{ root, file }] = pool
+      return { status: 'ok', source: await readFile(join(root, file), 'utf8'), path: file, cached: true }
+    }
+    if (pool.length > 1) {
+      return { status: 'ambiguous', candidates: pool.slice(0, 20).map((entry) => entry.file) }
+    }
+    return undefined
+  }
+
+  /**
+   * 只反编译一个类，源码直接来自 cfr 的标准输出。
+   */
+  async function decompileSingle(jar, className, signal) {
+    const argv = await cfrArgv(
+      [jar, normalizeClassPath(className).replace(/\//gu, '.')],
+      signal,
+    )
+    const result = await run(argv, {
+      cwd: dirname(jar),
+      signal,
+      maxBytes: SINGLE_CLASS_BYTES,
+      spill: false,
+    })
+    if (result.exitCode !== 0) return undefined
+    if (result.truncated) {
+      throw new Error(`单类源码超过 ${SINGLE_CLASS_BYTES} 字节，改为先用 jar_decompile 反编译整个 jar。`)
+    }
+    const source = result.stdout.trim()
+    return source ? `${source}\n` : undefined
+  }
+
+  /**
+   * 缓存目录里的全部 Java 源码相对路径。
+   */
+  async function listJavaFiles(root) {
+    const cached = listings.get(root)
+    if (cached) return cached
+    const files = []
+    const stack = ['']
+    while (stack.length > 0) {
+      const relative = stack.pop()
+      const entries = await readdir(join(root, relative), { withFileTypes: true })
+      for (const entry of entries) {
+        const child = relative ? `${relative}/${entry.name}` : entry.name
+        if (entry.isDirectory()) stack.push(child)
+        else if (entry.name.endsWith('.java')) files.push(child)
+      }
+    }
+    listings.set(root, files)
+    return files
+  }
+
+  /**
+   * 缓存目录按 jar 路径与内容指纹区分，jar 更新后自动落到新目录。
+   */
+  function cacheDirectory(jar, info) {
+    const digest = createHash('sha1')
+      .update(`${jar}|${info.size}|${info.mtimeMs}`)
+      .digest('hex')
+      .slice(0, 12)
+    const stem = basename(jar).replace(/[^\w.-]+/gu, '_')
+    return join(config.cacheDir, `${stem}-${digest}`)
+  }
+
+  return { decompile, readClass }
+}
+
+async function readMarker(marker) {
+  try {
+    const parsed = JSON.parse(await readFile(marker, 'utf8'))
+    return Number.isInteger(parsed?.classCount) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function readCollected(reader) {
+  if (!reader) return { text: '', lossy: false, spillPath: undefined }
+  const read = reader.readFrom(0)
+  return { text: read.text, lossy: read.lossy, spillPath: read.spillPath }
+}
+
+/**
+ * 类名统一成源码相对路径形式：`com.foo.Bar` 与 `com/foo/Bar` 都得到 `com/foo/Bar`。
+ */
+function normalizeClassPath(className) {
+  const trimmed = className.trim().replace(/\\/gu, '/').replace(/\.java$/iu, '')
+  if (trimmed.includes('/')) return trimmed
+  return trimmed.replace(/\./gu, '/')
+}
+
+function tail(text) {
+  return text.trim().slice(-2000)
+}

package/src/config.js

@@ -0,0 +1,52 @@
+/**
+ * 插件配置的默认值与规范化。
+ *
+ * 配置来自 Loader 行的 `config`；缺失字段一律回退默认值。
+ */
+
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 插件包根目录。 */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** 随包分发的 cfr.jar。 */
+export const BUNDLED_CFR = join(PACKAGE_ROOT, 'vendor', 'cfr.jar')
+
+/** 配置缺省值。 */
+export const DEFAULT_CONFIG = Object.freeze({
+  cacheDir: '',
+  javaPath: 'java',
+  cfrJar: BUNDLED_CFR,
+  rgPath: '',
+})
+
+/**
+ * DSH 数据根目录。
+ * @returns {string}
+ */
+function dshHome() {
+  const configured = process.env.DSH_HOME?.trim()
+  return configured || join(homedir(), '.dsh')
+}
+
+function text(value) {
+  if (value === undefined || value === null) return ''
+  return String(value).trim()
+}
+
+/**
+ * 把原始配置规范化成插件内部使用的完整配置。
+ * @param {Record<string, unknown>} [raw] Loader 行传入的 config
+ * @returns {{ cacheDir: string, javaPath: string, cfrJar: string, rgPath: string }}
+ */
+export function normalizeConfig(raw) {
+  const source = raw ?? {}
+  return {
+    cacheDir: text(source.cacheDir) || join(dshHome(), 'cache', 'jar-decompile'),
+    javaPath: text(source.javaPath) || DEFAULT_CONFIG.javaPath,
+    cfrJar: text(source.cfrJar) || DEFAULT_CONFIG.cfrJar,
+    rgPath: text(source.rgPath),
+  }
+}

package/src/rg.js

@@ -0,0 +1,103 @@
+/**
+ * ripgrep 调用层：在反编译源码目录里检索。
+ */
+
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+const GRACE_MS = 5000
+const COLLECT_BYTES = 512 * 1024
+const SPILL_BYTES = 2 * 1024 * 1024
+const FALLBACK_COMMAND = 'rg'
+
+/**
+ * @vscode/ripgrep 随包安装的 rg；依赖缺失时返回 undefined。
+ */
+function bundledRg() {
+  try {
+    const { rgPath } = require('@vscode/ripgrep')
+    return typeof rgPath === 'string' ? rgPath : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ rgPath: string }} config
+ */
+export function createRg(ctx, config) {
+  let rgExecutable
+
+  async function rgCommand(signal) {
+    if (!rgExecutable) {
+      const command = config.rgPath || bundledRg() || FALLBACK_COMMAND
+      rgExecutable = ctx.subprocess.resolveExecutable(command, undefined, signal)
+    }
+    try {
+      return await rgExecutable
+    } catch (error) {
+      rgExecutable = undefined
+      throw error
+    }
+  }
+
+  /**
+   * 在目录里按正则检索，返回逐行匹配。
+   * @param {{ dir: string, pattern: string, glob?: string, ignoreCase?: boolean, signal?: AbortSignal }} request
+   * @returns {Promise<{ matches: Array<{ path: string, line: number, text: string }>, truncated: boolean }>}
+   */
+  async function search({ dir, pattern, glob, ignoreCase, signal }) {
+    const rg = await rgCommand(signal)
+    const argv = [
+      rg,
+      '--line-number',
+      '--no-heading',
+      '--with-filename',
+      '--color=never',
+      '--no-config',
+      '-e',
+      pattern,
+    ]
+    if (ignoreCase) argv.push('--ignore-case')
+    if (glob) argv.push('--glob', glob)
+    const stdio = {
+      stdin: 'ignore',
+      stdout: { maxBytes: COLLECT_BYTES, spill: { maxBytes: SPILL_BYTES } },
+      stderr: { maxBytes: COLLECT_BYTES, spill: { maxBytes: SPILL_BYTES } },
+    }
+    const handle = ctx.subprocess.spawn({ argv, cwd: dir, stdio, graceMs: GRACE_MS, signal })
+    const outcome = await handle.done
+    const stdout = handle.collected.stdout?.readFrom(0) ?? { text: '', lossy: false }
+    const stderr = handle.collected.stderr?.readFrom(0) ?? { text: '', lossy: false }
+    if (outcome.exitCode !== 0 && outcome.exitCode !== 1) {
+      throw new Error(`rg 退出码 ${outcome.exitCode}：${stderr.text.trim().slice(0, 1000)}`)
+    }
+    return { matches: parseMatches(stdout.text), truncated: stdout.lossy }
+  }
+
+  return { search }
+}
+
+/**
+ * 解析 `path:line:text` 形式的匹配行；路径已相对检索目录。
+ */
+function parseMatches(text) {
+  const matches = []
+  for (const line of text.split(/\r?\n/u)) {
+    if (!line) continue
+    const first = line.indexOf(':')
+    if (first <= 0) continue
+    const second = line.indexOf(':', first + 1)
+    if (second < 0) continue
+    const lineNumber = Number(line.slice(first + 1, second))
+    if (!Number.isInteger(lineNumber)) continue
+    matches.push({
+      path: line.slice(0, first).replace(/\\/gu, '/'),
+      line: lineNumber,
+      text: line.slice(second + 1),
+    })
+  }
+  return matches
+}

package/src/tools.js

@@ -0,0 +1,298 @@
+/**
+ * 模型可调用的 jar 工具定义。
+ */
+
+import { isAbsolute, resolve } from 'node:path'
+
+const DEFAULT_READ_LIMIT = 400
+const MAX_READ_LIMIT = 2000
+const DEFAULT_MAX_MATCHES = 80
+const MAX_MAX_MATCHES = 500
+const DECOMPILE_TIMEOUT_MS = 900_000
+const READ_TIMEOUT_MS = 120_000
+
+/**
+ * 注册 jar_decompile、jar_search、jar_read 三个工具。
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ cfr: ReturnType<typeof import('./cfr.js').createCfr>, rg: ReturnType<typeof import('./rg.js').createRg> }} deps
+ * @returns {() => void} 注销函数
+ */
+export function registerJarTools(ctx, { cfr, rg }) {
+  const disposers = [
+    ctx.tools.register(decompileTool(cfr)),
+    ctx.tools.register(searchTool(cfr, rg)),
+    ctx.tools.register(readTool(cfr)),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+function decompileTool(cfr) {
+  return {
+    name: 'jar_decompile',
+    description: '把一个 jar 反编译成 Java 源码并缓存到本地目录，返回缓存目录。'
+      + '同一个 jar 只会真正反编译一次，之后命中缓存直接返回。'
+      + '需要在整个 jar 内检索时用它预热，或直接调用 jar_search（会自动确保已反编译）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        jar: {
+          type: 'string',
+          description: 'jar 文件路径；相对路径按当前会话工作目录解析。',
+        },
+      },
+      required: ['jar'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          ok: { type: 'boolean', description: '是否成功' },
+          jar: { type: 'string', description: '调用时传入的 jar' },
+          outDir: { type: 'string', description: '缓存里的源码目录' },
+          classCount: { type: 'number', description: '产出的 Java 文件数' },
+          cached: { type: 'boolean', description: '是否直接复用已有缓存' },
+          text: { type: 'string', description: '给模型读的正文' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: String(value?.text ?? '(无输出)') }],
+    },
+    timeoutMs: DECOMPILE_TIMEOUT_MS,
+    async execute(args, exec) {
+      const jar = requireString(args, 'jar')
+      if (!jar) return failure('jar 必须是非空字符串路径。')
+      const jarPath = resolveFrom(sessionCwd(exec), jar)
+      try {
+        const result = await cfr.decompile(jarPath, exec.signal)
+        return {
+          ok: true,
+          jar,
+          outDir: result.outDir,
+          classCount: result.classCount,
+          cached: result.cached,
+          text: [
+            `${result.cached ? '缓存已存在' : '反编译完成'}：${jar}`,
+            `输出目录：${result.outDir}`,
+            `Java 文件：${result.classCount}`,
+            '后续用 jar_search 检索源码，或用 jar_read 读取单个类。',
+          ].join('\n'),
+        }
+      } catch (error) {
+        return failure(`反编译失败：${messageOf(error)}`)
+      }
+    },
+  }
+}
+
+function searchTool(cfr, rg) {
+  return {
+    name: 'jar_search',
+    description: '在 jar 的反编译源码里用 ripgrep 做正则检索，返回 `文件:行号:内容`。'
+      + 'jar 尚未反编译时会自动先反编译。适合定位类、方法、字符串常量与调用点。'
+      + '用 glob 可以只搜某些包，例如 `**/util/*.java`。',
+    parameters: {
+      type: 'object',
+      properties: {
+        jar: {
+          type: 'string',
+          description: 'jar 文件路径；相对路径按当前会话工作目录解析。',
+        },
+        pattern: {
+          type: 'string',
+          description: 'ripgrep 正则表达式。',
+        },
+        glob: {
+          type: 'string',
+          description: '限定路径的 glob，例如 `**/service/*.java`。',
+        },
+        ignoreCase: {
+          type: 'boolean',
+          description: '是否忽略大小写。',
+        },
+        maxMatches: {
+          type: 'number',
+          description: `最多返回多少处匹配，默认 ${DEFAULT_MAX_MATCHES}，上限 ${MAX_MAX_MATCHES}。`,
+        },
+      },
+      required: ['jar', 'pattern'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          ok: { type: 'boolean', description: '是否成功' },
+          jar: { type: 'string', description: '调用时传入的 jar' },
+          total: { type: 'number', description: '匹配总数' },
+          shown: { type: 'number', description: '实际返回的匹配数' },
+          truncated: { type: 'boolean', description: '结果是否被截断' },
+          text: { type: 'string', description: '给模型读的正文' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: String(value?.text ?? '(无输出)') }],
+    },
+    timeoutMs: DECOMPILE_TIMEOUT_MS,
+    async execute(args, exec) {
+      const jar = requireString(args, 'jar')
+      const pattern = requireString(args, 'pattern')
+      if (!jar) return failure('jar 必须是非空字符串路径。')
+      if (!pattern) return failure('pattern 必须是非空正则表达式。')
+      const jarPath = resolveFrom(sessionCwd(exec), jar)
+      const glob = optionalString(args, 'glob')
+      try {
+        const compiled = await cfr.decompile(jarPath, exec.signal)
+        const result = await rg.search({
+          dir: compiled.outDir,
+          pattern,
+          glob,
+          ignoreCase: args?.ignoreCase === true,
+          signal: exec.signal,
+        })
+        const maxMatches = clampInt(args?.maxMatches, 1, MAX_MAX_MATCHES, DEFAULT_MAX_MATCHES)
+        const shown = result.matches.slice(0, maxMatches)
+        const total = result.matches.length
+        const lines = [total === 0
+          ? `没有匹配：${pattern}`
+          : `在 ${jar} 里匹配到 ${total} 处${total > shown.length ? `（显示前 ${shown.length} 处）` : ''}：`]
+        for (const match of shown) {
+          lines.push(`${match.path}:${match.line}:${match.text}`)
+        }
+        return {
+          ok: true,
+          jar,
+          total,
+          shown: shown.length,
+          truncated: result.truncated || total > shown.length,
+          text: lines.join('\n'),
+        }
+      } catch (error) {
+        return failure(`检索失败：${messageOf(error)}`)
+      }
+    },
+  }
+}
+
+function readTool(cfr) {
+  return {
+    name: 'jar_read',
+    description: '读取 jar 里一个类的反编译源码，按行返回。'
+      + '类名可以写全限定名 `com.foo.Bar`、内部名 `com/foo/Bar` 或短名 `Bar`；短名有多个候选时会列出候选。'
+      + '缓存里没有该类时会即时反编译这一个类。大文件用 offset 与 limit 翻页。',
+    parameters: {
+      type: 'object',
+      properties: {
+        jar: {
+          type: 'string',
+          description: 'jar 文件路径；相对路径按当前会话工作目录解析。',
+        },
+        className: {
+          type: 'string',
+          description: '类名，支持全限定名、内部名或短名。',
+        },
+        offset: {
+          type: 'number',
+          description: '起始行，1 基，默认 1。',
+        },
+        limit: {
+          type: 'number',
+          description: `读取行数，默认 ${DEFAULT_READ_LIMIT}，上限 ${MAX_READ_LIMIT}。`,
+        },
+      },
+      required: ['jar', 'className'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          ok: { type: 'boolean', description: '是否成功' },
+          jar: { type: 'string', description: '调用时传入的 jar' },
+          path: { type: 'string', description: '源码相对路径' },
+          totalLines: { type: 'number', description: '源码总行数' },
+          startLine: { type: 'number', description: '本次返回的起始行' },
+          text: { type: 'string', description: '给模型读的正文' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: String(value?.text ?? '(无输出)') }],
+    },
+    timeoutMs: READ_TIMEOUT_MS,
+    async execute(args, exec) {
+      const jar = requireString(args, 'jar')
+      const className = requireString(args, 'className')
+      if (!jar) return failure('jar 必须是非空字符串路径。')
+      if (!className) return failure('className 必须是非空类名。')
+      const jarPath = resolveFrom(sessionCwd(exec), jar)
+      const offset = clampInt(args?.offset, 1, Number.MAX_SAFE_INTEGER, 1)
+      const limit = clampInt(args?.limit, 1, MAX_READ_LIMIT, DEFAULT_READ_LIMIT)
+      try {
+        const result = await cfr.readClass(jarPath, className, exec.signal)
+        if (result.status === 'ambiguous') {
+          return failure(`类名有多个候选，请改用完整类名：\n${result.candidates.join('\n')}`)
+        }
+        if (result.status === 'missing') {
+          return failure(`没有找到类 ${className}：jar 内可能不存在该类，或类名写法有误。`)
+        }
+        const lines = result.source.split(/\r?\n/u)
+        const total = lines.length
+        const start = Math.min(offset, total)
+        const end = Math.min(total, start + limit - 1)
+        const body = lines
+          .slice(start - 1, end)
+          .map((line, index) => `${String(start + index).padStart(4, ' ')}  ${line}`)
+          .join('\n')
+        const remaining = total - end
+        return {
+          ok: true,
+          jar,
+          path: result.path,
+          totalLines: total,
+          startLine: start,
+          text: [
+            `${result.path}（共 ${total} 行，显示 ${start}-${end}）`,
+            body,
+            remaining > 0 ? `\n还有 ${remaining} 行，可增大 offset 继续读。` : '',
+          ].filter(Boolean).join('\n'),
+        }
+      } catch (error) {
+        return failure(`读取失败：${messageOf(error)}`)
+      }
+    },
+  }
+}
+
+function sessionCwd(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd ? cwd : process.cwd()
+}
+
+function resolveFrom(cwd, path) {
+  return isAbsolute(path) ? path : resolve(cwd, path)
+}
+
+function requireString(args, key) {
+  const value = args?.[key]
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  return value.trim()
+}
+
+function optionalString(args, key) {
+  const value = args?.[key]
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  return value.trim()
+}
+
+function clampInt(value, min, max, fallback) {
+  if (!Number.isInteger(value)) return fallback
+  return Math.min(max, Math.max(min, value))
+}
+
+function failure(text) {
+  return { ok: false, text }
+}
+
+function messageOf(error) {
+  return String(error?.message ?? error)
+}