hunter-mate 0.1.7 → 0.1.8

package/dist/commands/extras.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import WebSocket from 'ws';
 import * as readline from 'readline';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveDataDir } from '../config.js';
 import axios from 'axios';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -10,12 +10,114 @@ import { runStop, tryReadPid } from './server.js';
 import { i18n } from '../i18n/index.js';
 import { getCliLogger } from '../logger.js';
 /**
- * 通知所有已连接扩展 reload（自愈主链路）:
- * 1) 优先 HTTP POST /system/broadcast-extension（返回明确 broadcast 计数和错误）
- * 2) Fallback: 直连 WS /ws 发 {type:'broadcast', payload:{type:'reload'}}（兼容旧 server 无 HTTP 端点）
+ * FID-092:扫描扩展目录最新 mtime,等待其静止——reload 广播前确认 dist 已写完。
+ * 背景:R5 实机 reload 后 3 秒 dist 仍在写入,Chrome 重读读到写了一半的
+ * service-worker.js → SW eval 崩溃 → 无 alarm 监听/无 offscreen/零重连,
+ * 所有自愈路径全部失效,只能人工点。Windows 兼容:纯 node fs,无 shell。
+ */
+export async function waitForExtensionDirQuiet(dir, opts = {}) {
+    const quietMs = opts.quietMs ?? 2500;
+    const maxWaitMs = opts.maxWaitMs ?? 15000;
+    const pollMs = opts.pollMs ?? 400;
+    const start = Date.now();
+    const newestMtime = (d) => {
+        let latest = 0;
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return latest; // 目录不可读(未安装/权限)时不阻塞 reload
+        }
+        for (const e of entries) {
+            const full = path.join(d, e.name);
+            try {
+                if (e.isDirectory()) {
+                    latest = Math.max(latest, newestMtime(full));
+                }
+                else {
+                    latest = Math.max(latest, fs.statSync(full).mtimeMs);
+                }
+            }
+            catch {
+                /* 单个文件竞态删除,跳过 */
+            }
+        }
+        return latest;
+    };
+    let newest = newestMtime(dir);
+    while (newest > 0 && Date.now() - newest < quietMs && Date.now() - start < maxWaitMs) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        newest = newestMtime(dir);
+    }
+    return { quiet: newest === 0 || Date.now() - newest >= quietMs, waitedMs: Date.now() - start, newestMtimeMs: newest };
+}
+/** FID-092:轮询 server 已连接扩展数(>=1 即判定 reload 后已回连)。 */
+export async function extensionConnectedCount(serverUrl, timeoutMs = 3000) {
+    try {
+        const r = await axios.get(`${serverUrl}/extensions`, { timeout: timeoutMs, proxy: false });
+        return Array.isArray(r.data) ? r.data.length : 0;
+    }
+    catch {
+        return -1; // server 不可达
+    }
+}
+/**
+ * 通知所有已连接扩展 reload（自愈主链路）,FID-092 三段式:
+ * 1) dist 静止确认(防 reload 读到写一半的扩展文件)
+ * 2) 广播(broadcastReload):优先 HTTP POST /system/broadcast-extension;
+ *    旧 server 无该端点时退回直连 WS /ws 广播
+ * 3) 健康校验 + 自动重试(广播后 12s 内未回连 → 再广播,最多 3 次)
  */
 export async function runReload(timeoutMs = 5000) {
     const config = loadConfig();
+    // FID-092 步骤 1:dist 静止确认(软链/目录均可,扫描真实路径)
+    let extDir;
+    try {
+        extDir = fs.realpathSync(path.join(resolveDataDir(), 'extension'));
+    }
+    catch {
+        extDir = path.join(resolveDataDir(), 'extension');
+    }
+    const q = await waitForExtensionDirQuiet(extDir);
+    const quietNote = q.waitedMs > 500 ? `(等待 dist 写入静止 ${q.waitedMs}ms) ` : '';
+    // FID-092 步骤 2+3:广播 → 校验回连 → 失败重试
+    const VERIFY_WINDOW_MS = 12000;
+    const MAX_ATTEMPTS = 3;
+    let last = await broadcastReload(config, timeoutMs);
+    if (last.broadcast <= 0) {
+        return { ...last, msg: `${quietNote}${last.msg}` };
+    }
+    const start = Date.now();
+    while (Date.now() - start < VERIFY_WINDOW_MS) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const n = await extensionConnectedCount(config.serverUrl);
+        if (n > 0) {
+            return { ...last, msg: `${quietNote}${last.msg}；已校验扩展回连(connected=${n})。` };
+        }
+        if (n === -1)
+            break; // server 挂了,重试无意义
+    }
+    // 未回连:重试广播(第一次读到的可能是写了一半的文件,重读即恢复)
+    for (let attempt = 2; attempt <= MAX_ATTEMPTS; attempt++) {
+        await new Promise((r) => setTimeout(r, 1000));
+        last = await broadcastReload(config, timeoutMs);
+        if (last.broadcast <= 0)
+            break;
+        const deadline = Date.now() + VERIFY_WINDOW_MS;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 1000));
+            if ((await extensionConnectedCount(config.serverUrl)) > 0) {
+                return { ...last, msg: `${quietNote}第 ${attempt} 次广播后已校验扩展回连。` };
+            }
+        }
+    }
+    return {
+        ...last,
+        msg: `${quietNote}${MAX_ATTEMPTS} 次广播后扩展仍未回连(server /extensions=0)——扩展可能处于错误态,请到 chrome://extensions 查看 HunterMate「错误」并点「重新加载」。`,
+    };
+}
+async function broadcastReload(config, timeoutMs = 5000) {
     // ---------- 1) HTTP 优先（POST /system/broadcast-extension） ----------
     try {
         const res = await axios.post(`${config.serverUrl}/system/broadcast-extension`, { payload: { type: 'reload' } }, { timeout: timeoutMs, proxy: false });
@@ -29,6 +131,13 @@ export async function runReload(timeoutMs = 5000) {
                 msg: `reload 广播已通过 HTTP 通道发送给 ${broadcast} 个扩展实例：200ms 后每个实例会自动调 chrome.runtime.reload()，Chrome 将重新读取磁盘上的扩展文件。`,
             };
         }
+        // FID-086 deferred reload: server 已挂起意图,扩展重连(≤30s)自动下发——断连态不失败、不静默
+        if (body.queued) {
+            return {
+                broadcast: 0,
+                msg: '扩展当前未连接,重载请求已挂起:扩展重连(通常 ≤30 秒,chrome.alarms 唤醒)后将自动重新加载。无需手动干预。',
+            };
+        }
         if (errors.length) {
             return {
                 broadcast: 0,
@@ -143,7 +252,7 @@ export const openExtCommand = new Command('open-extension-folder')
 // ---------------------------------------------------------------------------
 // purge — 彻底清理本地 hunter-mate 数据
 // ---------------------------------------------------------------------------
-const HM_ROOT = () => path.join(process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.', '.hunter-mate');
+const HM_ROOT = resolveDataDir;
 /** 交互式二次确认 */
 function confirmPrompt(question) {
     return new Promise((resolve) => {

package/dist/commands/init.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-/** 对应 ChromePilot init: 创建 ~/.hunter-mate 目录、SQLite、初始 token */
+/** 对应 ChromePilot init: 创建数据目录、SQLite、初始 token(目录位置随 dataDir 配置,FID-071) */
 export declare function runInit(force?: boolean): {
     dir: string;
     extensionDir: string;

package/dist/commands/init.js

@@ -1,12 +1,11 @@
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as path from 'path';
-import { ensureConfigDir, loadConfig, saveConfig } from '../config.js';
+import { ensureConfigDir, loadConfig, saveConfig, resolveDataDir } from '../config.js';
 import { getCliLogger } from '../logger.js';
-/** 对应 ChromePilot init: 创建 ~/.hunter-mate 目录、SQLite、初始 token */
+/** 对应 ChromePilot init: 创建数据目录、SQLite、初始 token(目录位置随 dataDir 配置,FID-071) */
 export function runInit(force = false) {
-    const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-    const ROOT = path.join(HOME, '.hunter-mate');
+    const ROOT = resolveDataDir();
     const EXT_DIR = path.join(ROOT, 'extension');
     const DB_FILE = path.join(ROOT, 'hunter-mate.db');
     const SESSIONS_DIR = path.join(ROOT, 'sessions');

package/dist/commands/issue-env.d.ts

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+export interface IssueEnvGitInfo {
+    repoRoot: string;
+    head: string | null;
+    branch: string | null;
+    /** 最近一次提交(短 hash + 时间 + subject),与 issue 模板「代码 HEAD」行对应 */
+    lastCommit: string | null;
+    /** 有未提交改动 = dist 可能滞后于 HEAD,提 issue 必须注明 */
+    dirty: boolean;
+}
+export interface IssueEnvResult {
+    cliVersion: string;
+    /** dev = CLI 位于 git 工作区(软链/shim 到源码仓);package = 发布包安装 */
+    installType: 'dev' | 'package';
+    git: IssueEnvGitInfo | null;
+    /** server 未运行时为 null */
+    serverBuildTime: string | null;
+    os: string;
+    node: string;
+    dataDir: string;
+}
+export declare function runIssueEnv(): Promise<IssueEnvResult>;
+export declare const issueEnvCommand: Command;

package/dist/commands/issue-env.js

@@ -0,0 +1,101 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import axios from 'axios';
+import { i18n } from '../i18n/index.js';
+import { loadConfig, resolveDataDir } from '../config.js';
+import { readInstalledVersions } from '../version.js';
+// dev 软链/shim 安装时 __dirname 位于仓内(packages/cli/dist/commands),
+// 发布包安装时位于全局 node_modules —— 向上找含 .git 的目录即可判定并定位仓根。
+const START_DIR = path.dirname(fileURLToPath(import.meta.url));
+function findRepoRoot(start) {
+    let dir = start;
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** 静默执行 git,失败(git 不可用/非工作区)返回 null */
+function git(args, cwd) {
+    try {
+        const out = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runIssueEnv() {
+    const installed = readInstalledVersions();
+    const repoRoot = findRepoRoot(START_DIR);
+    let gitInfo = null;
+    if (repoRoot) {
+        const porcelain = git(['status', '--porcelain'], repoRoot) ?? '';
+        gitInfo = {
+            repoRoot,
+            head: git(['rev-parse', '--short', 'HEAD'], repoRoot),
+            branch: git(['branch', '--show-current'], repoRoot),
+            lastCommit: git(['log', '-1', '--format=%h %ci %s'], repoRoot),
+            dirty: porcelain.length > 0,
+        };
+    }
+    let serverBuildTime = null;
+    try {
+        const r = await axios.get(`${loadConfig().serverUrl}/health`, { timeout: 2000 });
+        serverBuildTime = r.data?.buildTime ?? null;
+    }
+    catch {
+        /* server 未运行,保持 null */
+    }
+    return {
+        cliVersion: installed.cli ?? 'unknown',
+        installType: repoRoot ? 'dev' : 'package',
+        git: gitInfo,
+        serverBuildTime,
+        os: `${os.platform()} ${os.release()} ${os.arch()}`,
+        node: process.version,
+        dataDir: resolveDataDir(),
+    };
+}
+function renderText(r) {
+    const lines = [];
+    lines.push(`${i18n.t('issueEnv.cliVersion')}: ${r.cliVersion}`);
+    lines.push(`${i18n.t('issueEnv.installType')}: ` +
+        (r.installType === 'dev' ? i18n.t('issueEnv.installDev') : i18n.t('issueEnv.installPackage')));
+    if (r.git) {
+        lines.push(`${i18n.t('issueEnv.gitHead')}: ${r.git.lastCommit ?? r.git.head ?? 'unknown'}`);
+        lines.push(`${i18n.t('issueEnv.gitBranch')}: ${r.git.branch ?? 'unknown'} · ` +
+            (r.git.dirty ? i18n.t('issueEnv.gitDirty') : i18n.t('issueEnv.gitClean')));
+        lines.push(`${i18n.t('issueEnv.repoRoot')}: ${r.git.repoRoot}`);
+    }
+    else {
+        lines.push(`${i18n.t('issueEnv.gitHead')}: ${i18n.t('issueEnv.gitUnavailable')}`);
+    }
+    lines.push(`${i18n.t('issueEnv.serverBuildTime')}: ${r.serverBuildTime ?? i18n.t('issueEnv.serverNotRunning')}`);
+    lines.push(`OS: ${r.os}`);
+    lines.push(`Node: ${r.node}`);
+    lines.push(`dataDir: ${r.dataDir}`);
+    return lines.join('\n');
+}
+export const issueEnvCommand = new Command('issue-env')
+    .description(i18n.t('issueEnv.description'))
+    .option('-f, --format <fmt>', '输出格式: text|json', 'text')
+    .action(async (opts) => {
+    const result = await runIssueEnv();
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(renderText(result));
+});

package/dist/commands/job.d.ts

@@ -3,8 +3,9 @@ export interface CreateJobCaseResult {
     id: number;
     externalId: string;
     status: string;
+    customerId?: number;
 }
-export declare function runJobCreate(folderPath: string): Promise<CreateJobCaseResult>;
+export declare function runJobCreate(folderPath: string, customerRef?: string): Promise<CreateJobCaseResult>;
 /**
  * 优先查 server 的 /job-cases;server 不可达或未登录时兜底本地 sqlite 缓存。
  */

package/dist/commands/job.js

@@ -8,6 +8,7 @@ import { loadConfig } from '../config.js';
 import { getToken } from '../keychain.js';
 import { i18n } from '../i18n/index.js';
 import { printCommandError } from '../utils/command-error.js';
+import { runCustomerList } from './customer.js';
 /** 递归收集目录下的 .md/.txt/.pdf(含 raw/jd/ 等子目录),键为相对路径(根目录文件不带前缀)。 */
 function collectJobFiles(dir, relPrefix = '', out = {}) {
     const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
@@ -24,10 +25,27 @@ function collectJobFiles(dir, relPrefix = '', out = {}) {
     }
     return out;
 }
-export async function runJobCreate(folderPath) {
+export async function runJobCreate(folderPath, customerRef) {
     const config = loadConfig();
     const token = await getToken();
     const headers = token ? { Authorization: `UTOKEN ${token}` } : {};
+    // --customer:按名称/别名解析客户 id,让职位 case 挂到客户锚点上
+    let customerId;
+    if (customerRef) {
+        if (/^\d+$/.test(customerRef.trim())) {
+            customerId = parseInt(customerRef.trim(), 10);
+        }
+        else {
+            const hits = await runCustomerList(customerRef.trim());
+            if (!hits.length) {
+                throw new Error(`客户 "${customerRef}" 未入库,请先: hunter-mate customer upsert --name "${customerRef}"`);
+            }
+            customerId = hits[0].id;
+            if (hits.length > 1) {
+                console.error(`ℹ 客户 "${customerRef}" 命中 ${hits.length} 条,使用第一个: [${hits[0].id}] ${hits[0].canonicalName}`);
+            }
+        }
+    }
     const resolved = path.resolve(folderPath);
     if (!fs.existsSync(resolved)) {
         throw new Error(`Folder not found: ${resolved}`);
@@ -45,6 +63,7 @@ export async function runJobCreate(folderPath) {
         title,
         folderPath: resolved,
         rawFiles,
+        customerId,
     }, { headers, proxy: false });
     const serverCase = res.data;
     ensureCacheDir();
@@ -92,13 +111,14 @@ export const jobCommand = new Command('job')
 jobCommand
     .command('create <folder>')
     .description(i18n.t('job.create'))
-    .action(async (folderPath) => {
+    .option('--customer <idOrName>', '关联客户(名称/别名/id),未入库会先报错提示 upsert')
+    .action(async (folderPath, opts) => {
     try {
-        const serverCase = await runJobCreate(folderPath);
-        console.log(`Created JobCase ${serverCase.id} (${serverCase.externalId})`);
+        const serverCase = await runJobCreate(folderPath, opts.customer);
+        console.log(`Created JobCase ${serverCase.id} (${serverCase.externalId})${serverCase.customerId ? ` customer=${serverCase.customerId}` : ''}`);
     }
     catch (err) {
-        printCommandError('job:create-failed', err);
+        await printCommandError('job:create-failed', err);
         process.exit(1);
     }
 });

package/dist/commands/login.d.ts

@@ -9,6 +9,10 @@ export declare function sendEmailCode(email: string): Promise<EmailLoginSource>;
 /**
  * 邮箱登录第二步:校验验证码并保存 token。
  * 分支选择与 sendEmailCode 保持一致:server 在线走本地代理自签,否则直连 SaaS。
+ *
+ * hmh#43:两个分支签发的 token 密钥不同,必须打 issuer 标记 —
+ * SaaS fallback 拿到的是 SaaS 签发的 token,本地 server 的 AuthMiddleware
+ * (USER_SESSION_SECRET)验不过,数据面(search 等)会 401。
  */
 export declare function verifyEmailCode(email: string, code: string): Promise<{
     token: string;

package/dist/commands/login.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import axios from 'axios';
 import open from 'open';
 import { loadConfig } from '../config.js';
-import { saveToken } from '../keychain.js';
+import { saveToken, getToken } from '../keychain.js';
 import { i18n } from '../i18n/index.js';
 import { getCliLogger } from '../logger.js';
 function sleep(ms) {
@@ -35,6 +35,10 @@ export async function sendEmailCode(email) {
 /**
  * 邮箱登录第二步:校验验证码并保存 token。
  * 分支选择与 sendEmailCode 保持一致:server 在线走本地代理自签,否则直连 SaaS。
+ *
+ * hmh#43:两个分支签发的 token 密钥不同,必须打 issuer 标记 —
+ * SaaS fallback 拿到的是 SaaS 签发的 token,本地 server 的 AuthMiddleware
+ * (USER_SESSION_SECRET)验不过,数据面(search 等)会 401。
  */
 export async function verifyEmailCode(email, code) {
     const config = loadConfig();
@@ -43,14 +47,17 @@ export async function verifyEmailCode(email, code) {
         if (!data.access_token) {
             throw new Error('verify returned no access_token');
         }
-        await saveToken(data.access_token);
+        await saveToken(data.access_token, 'local');
         return { token: data.access_token, source: 'server' };
     }
     const { data } = await axios.post(`${config.saasUrl}/hunter-mate/auth/email/verify`, { email, code }, { proxy: false });
     if (!data.access_token) {
         throw new Error('verify returned no access_token');
     }
-    await saveToken(data.access_token);
+    await saveToken(data.access_token, 'saas');
+    console.warn('⚠️  本地 server 未运行,本次登录由 SaaS 签发 token。\n' +
+        '    本地数据面(search 等)在 server 启动后会提示登录失效;\n' +
+        '    请先运行 hunter-mate server(或 hunter-mate extension check 自动拉起)再重新登录。');
     return { token: data.access_token, source: 'saas' };
 }
 export async function runLogin() {
@@ -111,6 +118,26 @@ export const loginCommand = new Command('login')
             }
             getCliLogger().info('login:token-saved', { method: 'email', email: options.email, source });
             console.log(i18n.t('login.success'));
+            // 登录后自检:拿新 token 打一次受保护端点,把「登录成功但搜索 401」的
+            // 静默失败变成确定的成功/失败提示(FID-057 #36)
+            try {
+                const token = await getToken();
+                const probe = await axios.get(`${loadConfig().serverUrl}/job-cases`, {
+                    headers: token ? { Authorization: `UTOKEN ${token}` } : {},
+                    timeout: 5000,
+                    proxy: false,
+                });
+                console.log(`${i18n.t('login.selfCheckOk')} (HTTP ${probe.status})`);
+            }
+            catch (probeErr) {
+                const status = probeErr?.response?.status;
+                if (status === 401 || status === 403) {
+                    console.error(`${i18n.t('login.selfCheckFail')} (HTTP ${status})`);
+                }
+                else {
+                    console.warn(`${i18n.t('login.selfCheckSkipped')} (HTTP ${status || 'network'})`);
+                }
+            }
             return;
         }
         if (options.code) {

package/dist/commands/migrate.d.ts

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+/**
+ * 跨卷安全移动:同卷 renameSync;rename 失败(典型 EXDEV 跨盘,Windows C:→D:)
+ * 回退递归 copy + rm。symlink 项读 link 目标后经 linkDev 重建
+ * (Windows 普通用户无 symlink 权限,junction/copy+marker 兜底)。
+ */
+export declare function moveEntry(src: string, dest: string): void;
+export interface MigrateResult {
+    from: string;
+    to: string;
+    moved: string[];
+    skipped: string[];
+    serverRestarted: boolean;
+}
+/**
+ * 数据目录迁移(FID-071):
+ * 1. server 在跑则先停(记录状态,迁移后按需重启)
+ * 2. 源目录(除 config.json 外)全部移动到目标目录
+ * 3. config.json 留在原 CONFIG_DIR,写入 dataDir=目标
+ * 4. 重启 server(若迁移前在跑)
+ */
+export declare function runMigrateDataDir(targetArg: string, deps: {
+    isRunning: () => Promise<boolean>;
+    stop: () => Promise<{
+        stopped: boolean;
+    }>;
+    start: () => Promise<{
+        started: boolean;
+        msg: string;
+    }>;
+}): Promise<MigrateResult>;
+export declare const migrateDataDirCommand: Command;

package/dist/commands/migrate.js

@@ -0,0 +1,116 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadConfig, saveConfig, resolveDataDir } from '../config.js';
+import { getCliLogger } from '../logger.js';
+import { linkDev } from '../utils/link.js';
+/**
+ * 跨卷安全移动:同卷 renameSync;rename 失败(典型 EXDEV 跨盘,Windows C:→D:)
+ * 回退递归 copy + rm。symlink 项读 link 目标后经 linkDev 重建
+ * (Windows 普通用户无 symlink 权限,junction/copy+marker 兜底)。
+ */
+export function moveEntry(src, dest) {
+    const stat = fs.lstatSync(src);
+    if (stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(src);
+        const r = linkDev(linkTarget, dest, stat.isDirectory() ? 'dir' : 'file');
+        if (!r.ok)
+            throw new Error(`重建软链失败 ${src} → ${dest}: ${r.error}`);
+        fs.unlinkSync(src);
+        return;
+    }
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch {
+        fs.cpSync(src, dest, { recursive: true });
+        fs.rmSync(src, { recursive: true, force: true });
+    }
+}
+/**
+ * 数据目录迁移(FID-071):
+ * 1. server 在跑则先停(记录状态,迁移后按需重启)
+ * 2. 源目录(除 config.json 外)全部移动到目标目录
+ * 3. config.json 留在原 CONFIG_DIR,写入 dataDir=目标
+ * 4. 重启 server(若迁移前在跑)
+ */
+export async function runMigrateDataDir(targetArg, deps) {
+    const target = path.resolve(targetArg);
+    const source = resolveDataDir();
+    if (target === source) {
+        throw new Error(`目标目录与当前数据目录相同: ${target}`);
+    }
+    if (target.startsWith(source + path.sep)) {
+        throw new Error(`目标目录不能位于当前数据目录内部: ${target}`);
+    }
+    if (!fs.existsSync(source)) {
+        throw new Error(`当前数据目录不存在: ${source}(先运行 hunter-mate init)`);
+    }
+    // 1) server 状态探测并停止
+    const wasRunning = await deps.isRunning();
+    if (wasRunning) {
+        const stopRes = await deps.stop();
+        if (!stopRes.stopped) {
+            throw new Error('server 停止失败,已中止迁移(避免移动正在被写入的数据库)');
+        }
+    }
+    // 2) 逐项移动(config.json 是配置的锚点,永远留在 CONFIG_DIR)
+    fs.mkdirSync(target, { recursive: true });
+    const entries = fs.readdirSync(source, { withFileTypes: true });
+    const moved = [];
+    const skipped = [];
+    for (const entry of entries) {
+        if (entry.name === 'config.json') {
+            skipped.push(entry.name);
+            continue;
+        }
+        moveEntry(path.join(source, entry.name), path.join(target, entry.name));
+        moved.push(entry.name);
+    }
+    // 3) 写回配置
+    saveConfig({ dataDir: target });
+    loadConfig();
+    // 4) 按需重启
+    let serverRestarted = false;
+    if (wasRunning) {
+        const startRes = await deps.start();
+        serverRestarted = startRes.started;
+        if (!startRes.started) {
+            getCliLogger().warn('migrate:server-restart-failed', { msg: startRes.msg });
+        }
+    }
+    return { from: source, to: target, moved, skipped, serverRestarted };
+}
+export const migrateDataDirCommand = new Command('migrate-data-dir')
+    .description('把 ~/.hunter-mate 的重数据(数据库/日志/缓存/扩展等)迁移到指定目录,如 D:\\hm-data(FID-071)')
+    .argument('<target>', '目标目录(绝对路径,如 D:\\hm-data)')
+    .action(async (target) => {
+    const { tryReadPid, runStop, runStart } = await import('./server.js');
+    const result = await runMigrateDataDir(target, {
+        isRunning: async () => {
+            const pid = tryReadPid();
+            if (!pid)
+                return false;
+            const config = loadConfig();
+            try {
+                const res = await fetch(`${config.serverUrl}/health`, {
+                    signal: AbortSignal.timeout(1500),
+                });
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+        stop: () => runStop(),
+        start: () => runStart({}),
+    });
+    console.log(`✓ 数据目录已迁移: ${result.from} → ${result.to}`);
+    console.log(`  移动 ${result.moved.length} 项: ${result.moved.join(', ') || '(空)'}`);
+    if (result.skipped.length) {
+        console.log(`  保留在原位: ${result.skipped.join(', ')}(配置文件锚点,不迁移)`);
+    }
+    console.log(`  server: ${result.serverRestarted ? '已重启' : '迁移前未运行(下次 start 自动使用新目录)'}`);
+    console.log('  提示: 若 Chrome 扩展加载自旧目录,请在新目录重新加载扩展(chrome://extensions)');
+    getCliLogger().info('migrate-data-dir:done', { from: result.from, to: result.to, moved: result.moved.length });
+});

package/dist/commands/note.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+/** 业务备注(Remark 实体)CLI 入口:推荐反馈/沟通结论/不合适原因等记忆载体 */
+export declare const noteCommand: Command;