dsh-app-deploy 0.3.0 → 0.4.0

package/README.md

@@ -31,7 +31,7 @@
 插件发布在 npm，通过 DSH 插件管理器直接安装：
 
 ```text
-plugin_manager → action: install_bundle → target: dsh-app-deploy@0.3.0
+plugin_manager → action: install_bundle → target: dsh-app-deploy@0.4.0
 ```
 
 安装后刷新 DSH Web，左侧导航出现「部署」入口。
@@ -49,6 +49,10 @@ plugin_manager → action: install_bundle → target: dsh-app-deploy@0.3.0
 
 新装插件默认为空配置（不播种），环境通过「+ 添加环境」或「导入」创建。
 
+## AI 工具
+
+插件向 dsh Agent 注册 4 个工具：`deploy_list_envs`（列出环境与模块，密码已剥离）、`deploy_run`（执行部署并返回日志）、`deploy_history`（执行记录）、`ssh_test_connection`（SSH 连通性测试）。可直接让 AI 代查发布状态或执行部署。
+
 ## 使用
 
 单模块部署流程：

package/client.js

@@ -74,7 +74,7 @@ window.__ModuleLoader__.load({
       while (modules.some((m) => m.id === 'mod' + n)) n++
       return {
         id: 'mod' + n, name: '新模块', kind: 'front', enabled: true,
-        buildCmd: '', sshId: '', localPath: '', remotePath: '',
+        buildCmd: '', sshId: '', instances: [], localPath: '', remotePath: '',
         postCommand: '', healthCheckUrl: '', frontEnv: '',
       }
     }
@@ -83,6 +83,7 @@ window.__ModuleLoader__.load({
         id: m.id || '', name: m.name || '', kind: m.kind === 'server' ? 'server' : 'front',
         enabled: m.enabled !== false,
         buildCmd: m.buildCmd || '', sshId: m.sshId || '',
+        instances: Array.isArray(m.instances) ? m.instances.map((i) => ({ sshId: i.sshId || '', healthCheckUrl: i.healthCheckUrl || '' })) : [],
         localPath: m.localPath || '', remotePath: m.remotePath || '', postCommand: m.postCommand || '',
         healthCheckUrl: m.healthCheckUrl || '', frontEnv: m.frontEnv || '',
       }
@@ -326,6 +327,28 @@ window.__ModuleLoader__.load({
             }))),
         h('div', { className: 'dad-hint' },
           '健康检查：HTTP 2xx、success=true、code=200；单次最多 5 秒，间隔 3 秒，最多等待 120 秒，失败中止后续模块。'),
+        h('div', { className: 'dad-instbox' },
+          h('div', { className: 'dad-insthead' },
+            h('span', { className: 'dad-label' }, '多实例（滚动发布：按顺序逐实例更新，探活通过才更新下一个；留空 = 单实例）'),
+            h('button', {
+              type: 'button', className: 'dad-btn', onClick: () => onChange('instances', [...(mod.instances || []), { sshId: (sshs[0] || {}).id || '', healthCheckUrl: '' }]),
+            }, '+ 添加实例')),
+          (mod.instances || []).map((inst, ii) => h('div', { key: ii, className: 'dad-inline', style: { marginBottom: '6px' } },
+            h('select', {
+              className: 'dad-select', value: inst.sshId, 'aria-label': '实例 ' + (ii + 1) + ' SSH 目标',
+              onChange: (ev) => onChange('instances', (mod.instances || []).map((x, j) => (j === ii ? { ...x, sshId: ev.target.value } : x))),
+            },
+              (sshs || []).map((s) => h('option', { key: s.id, value: s.id }, s.name || s.id))),
+            h('input', {
+              className: 'dad-input', type: 'text', value: inst.healthCheckUrl, placeholder: '探活 URL（可空，默认用模块的）',
+              'aria-label': '实例 ' + (ii + 1) + ' 健康检查 URL',
+              onChange: (ev) => onChange('instances', (mod.instances || []).map((x, j) => (j === ii ? { ...x, healthCheckUrl: ev.target.value } : x))),
+            }),
+            h('button', {
+              type: 'button', className: 'dad-btndel', title: '删除实例', 'aria-label': '删除实例 ' + (ii + 1),
+              style: { position: 'static' },
+              onClick: () => onChange('instances', (mod.instances || []).filter((_, j) => j !== ii)),
+            }, '×')))),
         mod.kind === 'front'
           ? h('div', { className: 'dad-row' },
             h(Field, { label: feLabel, wide: true },
@@ -1067,6 +1090,7 @@ window.__ModuleLoader__.load({
             enabled: !!m.enabled,
             buildCmd: (m.buildCmd || '').trim(),
             sshId: (m.sshId || '').trim(),
+            instances: (m.instances || []).map((i) => ({ sshId: (i.sshId || '').trim(), healthCheckUrl: (i.healthCheckUrl || '').trim() })),
             localPath: (m.localPath || '').trim(),
             remotePath: (m.remotePath || '').trim(),
             postCommand: (m.postCommand || '').trim(),
@@ -1238,9 +1262,15 @@ window.__ModuleLoader__.load({
           const exp = m.kind === 'server' && env.expTime && ((m.buildCmd || '').trim().split(/\s+/)[0] || '').includes('gradle') ? ' -PexpTime=' + env.expTime : ''
           lines.push('')
           lines.push('[' + (m.name || m.id) + ']')
-          const target = targetOf(env, m)
           lines.push('  构建: ' + m.buildCmd + exp)
-          lines.push('  rsync: ' + m.localPath + ' → ' + (target.user || 'root') + '@' + (target.host || '?') + ':' + m.remotePath + (env.sshs && env.sshs.length > 1 ? '（目标: ' + (target.name || target.id) + '）' : ''))
+          const insts = (m.instances || []).length
+            ? m.instances.map((inst, ii) => ({ target: targetOf(env, { sshId: inst.sshId }), healthCheckUrl: inst.healthCheckUrl || m.healthCheckUrl, label: '实例' + (ii + 1) }))
+            : [{ target: targetOf(env, m), healthCheckUrl: m.healthCheckUrl, label: '' }]
+          for (const inst of insts) {
+            const t = inst.target
+            lines.push('  ' + (inst.label ? inst.label + ' ' : '') + 'rsync: ' + m.localPath + ' → ' + (t.user || 'root') + '@' + (t.host || '?') + ':' + m.remotePath + (inst.label ? '' : (env.sshs && env.sshs.length > 1 ? '（目标: ' + (t.name || t.id) + '）' : '')))
+            if (inst.healthCheckUrl) lines.push('    探活: ' + inst.healthCheckUrl)
+          }
           if (m.postCommand) lines.push('  ssh: ' + m.postCommand)
         }
         return lines.join('\n')

package/index.js

@@ -7,6 +7,7 @@ import { initConfig } from './server/config.js'
 import { initHistory } from './server/history.js'
 import { handleRpc } from './server/rpc.js'
 import { handleDeploy, killActiveProcess } from './server/deployment.js'
+import { registerTools } from './server/tools.js'
 
 // ponytail: linked workspace cannot resolve dsh's own packages; resolve from the dsh entry instead
 function hostRequire() {
@@ -22,7 +23,7 @@ const host = hostRequire()
 const schema = host('@deepseek-ai/schemastery')
 const z = schema.z ?? schema
 
-export const inject = ['webServer']
+export const inject = ['webServer', 'tools']
 export const Config = z.object({
   dataDir: z.string().default(''),
   defaultProjectPath: z.string().default(''),
@@ -59,13 +60,19 @@ function resolveDataDir(config) {
 
 export function apply(ctx, config) {
   const dataDir = resolveDataDir(config)
-  // 延迟初始化：apply 内不 await，首个请求时才读数据目录/初始化配置
+  // 延迟初始化：apply 内不 await，首个请求/工具调用时才读数据目录/初始化配置
   let ready
   const ensure = () => (ready ??= (async () => {
     await mkdir(dataDir, { recursive: true })
     await initConfig({ dataDir, defaultProjectPath: config?.defaultProjectPath || '' })
     await initHistory(dataDir)
   })())
+  // AI 工具：列出环境 / 执行部署 / 执行记录 / SSH 测试（defineTool 从 dsh 宿主解析，失败不影响面板）
+  try {
+    registerTools(ctx, host('@deepseek-ai/dsh-tools').defineTool, ensure)
+  } catch (err) {
+    console.warn('[dsh-app-deploy] 注册 AI 工具失败:', err?.message || err)
+  }
 
   ctx.effect(() => {
     const dispose = ctx.webServer.register({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-app-deploy",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "DSH 插件：按环境编排并执行构建（Gradle/Maven/前端）、多 SSH 目标发布、rsync/rclone 同步与远程命令的部署面板，支持连接测试，实时推送日志并保留执行记录。",
   "repository": "btboys/dsh-app-deploy",
   "type": "module",

package/server/config.js

@@ -64,6 +64,27 @@ export function targetFor(env, m) {
   return list.find((s) => s.id === m?.sshId) || list[0]
 }
 
+// 模块的多实例发布列表：每个实例指定 SSH 目标与探活 URL（URL 可空 = 该实例不探活直接继续）；
+// 无实例配置 = 模块自身单实例（用模块默认目标与健康检查 URL）
+export function instanceList(env, m) {
+  if (!Array.isArray(m?.instances) || !m.instances.length) {
+    return [{ target: targetFor(env, m), healthCheckUrl: (m?.healthCheckUrl || '').trim(), label: '' }]
+  }
+  return m.instances.map((inst, i) => ({
+    target: targetFor(env, { ...m, sshId: inst.sshId }),
+    healthCheckUrl: (inst.healthCheckUrl || m.healthCheckUrl || '').trim(),
+    label: `实例${i + 1}`,
+  }))
+}
+
+// 实例数组归一化：只保留带 sshId 的项
+function normInstances(raw) {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .map((i) => ({ sshId: String(i?.sshId || ''), healthCheckUrl: String(i?.healthCheckUrl || '').trim() }))
+    .filter((i) => i.sshId)
+}
+
 // 把 modules 归一化为数组；record 旧格式自动转数组（id 保持 bsFront 等，name 映射），frontEnv.bs/admin 迁移进对应 front 模块
 function toModArray(mods, fe) {
   const out = []
@@ -78,6 +99,7 @@ function toModArray(mods, fe) {
         enabled: raw?.enabled !== false,
         buildCmd: String(raw?.buildCmd || cmdFromGradle(raw?.gradleTask, raw?.key, raw?.extraArgs)),
         sshId: String(raw?.sshId || ''),
+        instances: normInstances(raw?.instances),
         localPath: String(raw?.localPath || ''),
         remotePath: String(raw?.remotePath || ''),
         postCommand: String(raw?.postCommand || ''),
@@ -95,6 +117,7 @@ function toModArray(mods, fe) {
         enabled: m.enabled !== false,
         buildCmd: String(m.buildCmd || cmdFromGradle(m.gradleTask, m.key, m.extraArgs)),
         sshId: String(m.sshId || ''),
+        instances: normInstances(m.instances),
         localPath: String(m.localPath || ''), remotePath: String(m.remotePath || ''), postCommand: String(m.postCommand || ''),
         frontEnv: feText,
       })
@@ -257,6 +280,16 @@ export function validateEnv(e) {
     }
     if (!m.enabled) continue
     if (m.sshId && !sshList.some((s) => s.id === m.sshId)) errs.push(`${m.name || m.id}: SSH 目标「${m.sshId}」不存在`)
+    for (let ii = 0; ii < (m.instances || []).length; ii++) {
+      const inst = m.instances[ii]
+      if (!sshList.some((s) => s.id === inst.sshId)) errs.push(`${m.name || m.id}: 实例${ii + 1} 的 SSH 目标「${inst.sshId}」不存在`)
+      if (inst.healthCheckUrl) {
+        try {
+          const url = new URL(inst.healthCheckUrl)
+          if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('invalid URL')
+        } catch { errs.push(`${m.name || m.id}: 实例${ii + 1} 的健康检查 URL 必须是 HTTP/HTTPS 地址，且不能包含用户名或密码`) }
+      }
+    }
     if (!m.buildCmd.trim()) errs.push(`${m.name || m.id}: 构建命令必填（如 ./gradlew …、mvn …、npm run build）`)
     else if (BAD_CMD.test(m.buildCmd)) errs.push(`${m.name || m.id}: 构建命令含非法字符（禁止引号/; & | \` $ 等）`)
     if (!m.localPath) errs.push(`${m.name || m.id}: 本地产物路径必填`)

package/server/deployment.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process'
 import { promises as fsp, existsSync } from 'node:fs'
 import path from 'node:path'
-import { getEnvs, targetFor } from './config.js'
+import { getEnvs, instanceList } from './config.js'
 import { getHistory, saveHistory, LOGTAIL_CHARS } from './history.js'
 import { listWorktrees, which, rcloneObscure } from './local-tools.js'
 import { checkHealth } from './health-check.js'
@@ -238,12 +238,10 @@ export function buildRcloneArgs(target, m, local, rclone) {
   return args
 }
 
-// 返回退出码与失败阶段（清理/构建/同步/远程命令），用于执行记录
+// 返回退出码与失败阶段（清理/构建/同步/远程命令/健康检查），用于执行记录
 // rclone 非空时用 rclone（SFTP）替代 rsync 同步；rsyncEnv 同时承载 sshpass 的 SSHPASS
-// target 为模块选中的 SSH 目标（env.sshs 之一）
-export async function deployModule(env, m, target, sshpass, rclone = null) {
-  const sshBase = `ssh -p ${target.port}${target.keyFile ? ' -i ' + target.keyFile : ''}${target.options ? ' ' + target.options : ''}`
-  const dest = `${target.user}@${target.host}`
+// 发布目标不再作为参数：模块可能多实例（instanceList），逐实例在内部解析
+export async function deployModule(env, m, sshpass, rclone = null) {
   // 0. 清理构建目录（恢复原 update-*.sh 行为）
   const c0 = await cleanBuildDir(env, m)
   if (c0 !== 0) return { code: c0, step: '清理' }
@@ -284,38 +282,52 @@ export async function deployModule(env, m, target, sshpass, rclone = null) {
   const c1 = await runStep(`[${m.name}] 构建: ${buildArgs.join(' ')} ${noteSuffix}`, buildArgs, { cwd: env.projectPath, env: envForGradle, shell: IS_WIN })
   if (c1 !== 0) { broadcast(`[${m.name}] 构建失败，退出码 ${c1}，中止部署\n`); return { code: c1, step: '构建' } }
 
-  // 2. 同步：优先 rsync；本机没有时回退 rclone（--delete 仅用于前端模块，与原脚本行为一致）
+  // 2/3. 多实例滚动发布：按实例列表顺序，逐个 同步 → 远程命令 → 探活；探活通过才更新下一个实例。
+  // 无实例配置 = 单实例（模块默认目标与健康检查 URL）。
   const isFront = m.kind === 'front'
   // 保留 rsync 的目录尾斜杠语义：dist/ 传内容本身，dist 传 dist 目录
   const isDirLike = /[\\/]$/.test(m.localPath)
   const joined = path.isAbsolute(m.localPath) ? m.localPath : path.join(env.projectPath, m.localPath)
   const local = joined.replace(/[\\/]+$/, '') + (isDirLike ? '/' : '')
-  const rsyncEnv = sshpass ? { ...process.env, SSHPASS: target.password } : process.env
-  let c2
-  if (rclone) {
-    const args = buildRcloneArgs(target, m, local, rclone)
-    c2 = await runStep(`[${m.name}] rclone ${isFront ? 'sync' : 'copy'} ${local} → :sftp:${m.remotePath}${isFront ? '（镜像 --delete）' : ''}`, [rclone.bin, ...args], {})
-  } else {
-    const rsyncArgs = ['rsync', '-r', '-t', '-z', '-e', sshpass ? `sshpass -e ${sshBase}` : sshBase]
-    if (isFront) rsyncArgs.push('--delete', '--exclude=.user.ini') // 排除宝塔 .user.ini（chattr +i 锁定，--delete 无法删除且会导致退出码非 0）
-    rsyncArgs.push(local, `${dest}:${m.remotePath}`)
-    c2 = await runStep(`[${m.name}] rsync ${local} → ${dest}:${m.remotePath}${isFront ? '（--delete）' : ''}`, rsyncArgs, { env: rsyncEnv })
-  }
-  if (c2 !== 0) { broadcast(`[${m.name}] 同步失败，退出码 ${c2}，中止部署\n`); return { code: c2, step: '同步' } }
+  const instances = instanceList(env, m)
+  if (instances.length > 1) broadcast(`[${m.name}] 多实例滚动发布：共 ${instances.length} 个实例，探活通过才更新下一个\n`)
+  for (let ii = 0; ii < instances.length; ii++) {
+    const inst = instances[ii]
+    const t = inst.target
+    const prefix = instances.length > 1 ? `[${m.name} ${inst.label}]` : `[${m.name}]`
+    const sshBase = `ssh -p ${t.port}${t.keyFile ? ' -i ' + t.keyFile : ''}${t.options ? ' ' + t.options : ''}`
+    const dest = `${t.user}@${t.host}`
+    // 仅当该实例目标配置了密码才挂 sshpass（避免空 SSHPASS 破坏密钥/agent 认证）
+    const usePass = sshpass && t.password
+    const rsyncEnv = usePass ? { ...process.env, SSHPASS: t.password } : process.env
+    // 2. 同步：优先 rsync；本机没有时回退 rclone（--delete 仅用于前端模块，与原脚本行为一致）
+    let c2
+    if (rclone) {
+      const args = buildRcloneArgs(t, m, local, rclone)
+      c2 = await runStep(`${prefix} rclone ${isFront ? 'sync' : 'copy'} ${local} → :sftp:${m.remotePath}${isFront ? '（镜像 --delete）' : ''}`, [rclone.bin, ...args], {})
+    } else {
+      const rsyncArgs = ['rsync', '-r', '-t', '-z', '-e', usePass ? `sshpass -e ${sshBase}` : sshBase]
+      if (isFront) rsyncArgs.push('--delete', '--exclude=.user.ini') // 排除宝塔 .user.ini（chattr +i 锁定，--delete 无法删除且会导致退出码非 0）
+      rsyncArgs.push(local, `${dest}:${m.remotePath}`)
+      c2 = await runStep(`${prefix} rsync ${local} → ${dest}:${m.remotePath}${isFront ? '（--delete）' : ''}`, rsyncArgs, { env: rsyncEnv })
+    }
+    if (c2 !== 0) { broadcast(`${prefix} 同步失败，退出码 ${c2}，中止部署\n`); return { code: c2, step: instances.length > 1 ? `同步（${inst.label}）` : '同步' } }
 
-  // 3. ssh 远程命令
-  if (m.postCommand.trim()) {
-    const sshArgs = []
-    if (sshpass) sshArgs.push('sshpass', '-e')
-    sshArgs.push('ssh', '-p', String(target.port))
-    if (target.keyFile) sshArgs.push('-i', target.keyFile)
-    if (target.options) sshArgs.push(...target.options.trim().split(/\s+/).filter(Boolean))
-    sshArgs.push(dest, m.postCommand.trim())
-    const c3 = await runStep(`[${m.name}] 远程执行: ${m.postCommand.trim()}`, sshArgs, { env: rsyncEnv })
-    if (c3 !== 0) { broadcast(`[${m.name}] 远程命令失败，退出码 ${c3}，中止部署\n`); return { code: c3, step: '远程命令' } }
-  }
-  if (!await checkHealth(m.healthCheckUrl || '', message => broadcast(`[${m.name}] ${message}`))) {
-    return { code: 1, step: '健康检查' }
+    // 3. ssh 远程命令
+    if (m.postCommand.trim()) {
+      const sshArgs = []
+      if (usePass) sshArgs.push('sshpass', '-e')
+      sshArgs.push('ssh', '-p', String(t.port))
+      if (t.keyFile) sshArgs.push('-i', t.keyFile)
+      if (t.options) sshArgs.push(...t.options.trim().split(/\s+/).filter(Boolean))
+      sshArgs.push(dest, m.postCommand.trim())
+      const c3 = await runStep(`${prefix} 远程执行: ${m.postCommand.trim()}`, sshArgs, { env: rsyncEnv })
+      if (c3 !== 0) { broadcast(`${prefix} 远程命令失败，退出码 ${c3}，中止部署\n`); return { code: c3, step: instances.length > 1 ? `远程命令（${inst.label}）` : '远程命令' } }
+    }
+    // 探活：通过才继续下一个实例（滚动发布闸门）
+    if (!await checkHealth(inst.healthCheckUrl || '', message => broadcast(`${prefix} ${message}`))) {
+      return { code: 1, step: instances.length > 1 ? `健康检查（${inst.label}）` : '健康检查' }
+    }
   }
   return { code: 0, step: null }
 }
@@ -329,7 +341,7 @@ async function runDeployment(env, mods) {
     const rcloneBin = hasRsync ? null : await which('rclone')
     const needSsh = mods.some(m => m.enabled && m.postCommand.trim())
     // 每个启用的模块按其 sshId 解析发布目标（env.sshs 之一）
-    const usedTargets = [...new Set(mods.filter(m => m.enabled).map(m => targetFor(env, m)))]
+    const usedTargets = [...new Set(mods.filter(m => m.enabled).flatMap(m => instanceList(env, m).map(i => i.target)))]
     const missing = []
     if (!hasRsync && !rcloneBin) missing.push('rsync（或 rclone）')
     if ((hasRsync || needSsh) && !(await which('ssh'))) missing.push('ssh')
@@ -354,17 +366,21 @@ async function runDeployment(env, mods) {
       code = 0
       for (const m of mods) {
         if (!m.enabled) { broadcast(`[跳过] ${m.name} 已禁用\n`); continue }
-        const target = targetFor(env, m)
-        if (rclone && target.password && !passCache.has(target.password)) {
-          const pass = await rcloneObscure(rcloneBin, target.password)
-          if (!pass) {
-            broadcast(`错误: rclone obscure 密码处理失败（目标 ${target.name}），无法使用密码认证\n`)
-            code = 127
-            break
+        // 预检该模块所有实例目标的 rclone 密码（逐实例 obscure，按密码缓存）
+        for (const inst of instanceList(env, m)) {
+          const target = inst.target
+          if (rclone && target.password && !passCache.has(target.password)) {
+            const pass = await rcloneObscure(rcloneBin, target.password)
+            if (!pass) {
+              broadcast(`错误: rclone obscure 密码处理失败（目标 ${target.name}），无法使用密码认证\n`)
+              code = 127
+              break
+            }
+            passCache.set(target.password, pass)
           }
-          passCache.set(target.password, pass)
         }
-        const res = await deployModule(env, m, target, target.password ? sshpass : null, rclone)
+        if (code !== 0) break
+        const res = await deployModule(env, m, sshpass, rclone)
         if (res.code !== 0) {
           if (running?.record) { running.record.failedModule = m.name; running.record.failedStep = res.step }
           code = res.code
@@ -405,7 +421,7 @@ export async function handleDeploy(req, res, url) {
   const mods = orderIds.map(id => ordered.find(m => m.id === id)).filter(m => !!m)
   if (!mods.length) return bad('所选模块在环境中均不可用或已禁用')
   // 所选模块涉及的 SSH 目标都必须有 host/user
-  const runTargets = [...new Set(mods.map(m => targetFor(env, m)))]
+  const runTargets = [...new Set(mods.flatMap(m => instanceList(env, m).map(i => i.target)))]
   if (runTargets.some(t => !t.host || !t.user)) return bad('SSH 目标配置不完整')
 
   const sseHeaders = { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' }
@@ -463,4 +479,45 @@ export async function handleDeploy(req, res, url) {
   }
 }
 
+// 供 AI 工具调用：同步执行一次部署并返回结果；与 SSE 入口共用部署锁、执行记录与日志尾部
+export async function runDeploy(envId, moduleIds = []) {
+  const env = getEnvs().find(e => e.id === envId)
+  if (!env) throw new Error(`未知环境: ${envId}`)
+  if (running && !running.done) throw new Error(`已有部署进行中（${running.label}），请稍后再试`)
+  const want = (moduleIds || []).filter(Boolean)
+  const enabled = env.modules.filter(m => m.enabled)
+  // 未指定模块 = 全部启用模块（按配置顺序）；指定则按给定顺序
+  const mods = want.length
+    ? want.map(id => enabled.find(m => m.id === id)).filter(Boolean)
+    : enabled
+  if (!mods.length) throw new Error('没有可部署的启用模块（检查模块 ID 与启用状态）')
+  if (want.length && mods.length !== want.length) {
+    const missing = want.filter(id => !enabled.some(m => m.id === id))
+    throw new Error(`模块不可用或已禁用: ${missing.join('、')}`)
+  }
+  const runTargets = [...new Set(mods.flatMap(m => instanceList(env, m).map(i => i.target)))]
+  if (runTargets.some(t => !t.host || !t.user)) throw new Error('SSH 目标配置不完整')
+
+  const rec = {
+    id: Date.now().toString(36) + Math.random().toString(36).slice(2, 8),
+    envId: env.id, envName: env.name,
+    modules: mods.map(m => ({ id: m.id, name: m.name })),
+    startTime: Date.now(), endTime: null, durationMs: null,
+    status: 'running', exitCode: null, failedModule: null, failedStep: null, logTail: '',
+  }
+  getHistory().push(rec)
+  saveHistory().catch(() => {})
+  running = { clients: new Set(), done: false, label: `${env.name} / ${mods.map(m => m.name).join('+')}`, record: rec, logTail: '', lastCode: null }
+  broadcast(`>>> 开始部署 [AI 工具] ${env.name} / ${mods.map(m => m.name).join('+')}\n`)
+  await runDeployment(env, mods) // 结束后 running.done 已置位、rec 已补齐
+  return {
+    code: rec.exitCode,
+    status: rec.status,
+    durationMs: rec.durationMs,
+    failedModule: rec.failedModule,
+    failedStep: rec.failedStep,
+    logTail: rec.logTail,
+  }
+}
+
 export function activeRecord() { return running && !running.done ? running.record : null }

package/server/tools.js

@@ -0,0 +1,139 @@
+// AI 可调用的部署工具：列出环境、执行部署、查执行记录、测试 SSH 连接
+// 密码绝不暴露给模型（只返回 hasPassword 标记）；密钥路径是本机路径，可返回
+import { getEnvs } from './config.js'
+import { runDeploy, testSsh, activeRecord } from './deployment.js'
+import { getHistory } from './history.js'
+
+// 环境摘要：供模型决定部署目标；剥离 password
+export function envSummaryForModel(e) {
+  return {
+    id: e.id, name: e.name, note: e.note, group: e.group,
+    projectPath: e.projectPath, jdkHome: e.jdkHome || '', nodeHome: e.nodeHome || '', pmPath: e.pmPath || '',
+    sshs: (e.sshs || []).map(s => ({
+      id: s.id, name: s.name, host: s.host, port: s.port, user: s.user,
+      hasPassword: !!s.password, keyFile: s.keyFile || '', options: s.options || '',
+    })),
+    modules: (e.modules || []).map(m => ({
+      id: m.id, name: m.name, kind: m.kind, enabled: m.enabled, buildCmd: m.buildCmd, sshId: m.sshId || '',
+      localPath: m.localPath, remotePath: m.remotePath, postCommand: m.postCommand, healthCheckUrl: m.healthCheckUrl || '',
+      instances: (m.instances || []).map((i) => ({ sshId: i.sshId, healthCheckUrl: i.healthCheckUrl })),
+    })),
+  }
+}
+
+const jsonRender = (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+
+/**
+ * 向 ctx.tools 注册 4 个工具。defineTool 由宿主解析（@deepseek-ai/dsh-tools），
+ * 插件自身不依赖该包，保证脱离 dsh 宿主时模块仍可加载（如单元测试）。
+ * @param {object} ctx cordis Context（需注入 tools 服务）
+ * @param {object} defineTool @deepseek-ai/dsh-tools 的 defineTool
+ * @param {() => Promise<void>} ensure 插件初始化（数据目录/配置/历史）；工具调用不走 HTTP 路由，必须显式等待
+ */
+export function registerTools(ctx, defineTool, ensure) {
+  // 每个工具执行前确保初始化完成（幂等，首次才真正读盘）
+  const ready = () => (ensure ? ensure() : Promise.resolve())
+  ctx.tools.register(defineTool({
+    name: 'deploy_list_envs',
+    description: 'List deploy environments configured in the dsh-app-deploy plugin: SSH targets (passwords stripped), build modules with their build commands, artifact paths, publish targets and rolling-update instances. Use before deploy_run to pick env/module IDs.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          active: { type: 'object', additionalProperties: true }, // 进行中的部署（无则不返回）
+          envs: { type: 'array', required: true, items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: jsonRender,
+    },
+    execute: async () => {
+      await ready()
+      const rec = activeRecord()
+      return {
+        ...(rec ? { active: { id: rec.id, env: rec.envName, modules: rec.modules } } : {}),
+        envs: getEnvs().map(envSummaryForModel),
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'deploy_run',
+    description: 'Run a deployment for one environment: clean → build each module (generic command: gradlew/mvn/npm…) → rsync/rclone to the module\'s SSH target → remote command → health check. Blocks until finished and returns the exit code plus the full log tail. Fails if another deployment is running. Omit modules to deploy all enabled modules in config order.',
+    parameters: {
+      env: { type: 'string', required: true, description: 'Environment ID (from deploy_list_envs)' },
+      modules: { type: 'array', items: { type: 'string' }, description: 'Module IDs in desired execution order. Omit for all enabled modules.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          code: { type: 'integer', required: true },
+          status: { type: 'string', required: true },
+          durationMs: { type: 'integer' },
+          failedModule: { type: 'string' },
+          failedStep: { type: 'string' },
+          logTail: { type: 'string', required: true },
+        },
+      },
+      render: jsonRender,
+    },
+    execute: async (args) => {
+      await ready()
+      return runDeploy(args.env, args.modules || [])
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'deploy_history',
+    description: 'Recent deployment records (newest first): status, duration, per-module failure step, and a truncated log tail for failed runs. Filter by environment ID optionally.',
+    parameters: {
+      env: { type: 'string', description: 'Environment ID to filter by' },
+      limit: { type: 'integer', description: 'Max records, default 10' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          records: { type: 'array', required: true, items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: jsonRender,
+    },
+    execute: async (args) => {
+      await ready()
+      const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 50)
+      let list = getHistory().slice()
+      if (args.env) list = list.filter(r => r.envId === args.env)
+      return { records: list.slice(-limit).reverse() }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ssh_test_connection',
+    description: 'Test an SSH connection (10s timeout): host key/agent auth via keyFile, or password via sshpass. Returns ok/latency or the server-reported error.',
+    parameters: {
+      host: { type: 'string', required: true },
+      port: { type: 'integer' },
+      user: { type: 'string', required: true },
+      password: { type: 'string', description: 'SSH password; omit to use keyFile or agent' },
+      keyFile: { type: 'string', description: 'Absolute private key path; takes precedence over options -i' },
+      options: { type: 'string', description: 'Extra ssh options, e.g. -o StrictHostKeyChecking=no' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          ms: { type: 'integer' },
+          error: { type: 'string' },
+        },
+      },
+      render: jsonRender,
+    },
+    execute: async (args) => {
+      await ready()
+      return testSsh({ host: args.host, port: args.port || 22, user: args.user, password: args.password || '', keyFile: args.keyFile || '', options: args.options || '' })
+    },
+  }))
+}