hunter-mate 0.1.7 → 0.1.11

package/dist/extension-sync.js

@@ -0,0 +1,159 @@
+// extension-sync.ts — CLI 内置扩展产物 ↔ ~/.hunter-mate/extension 同步(Issue #23)
+//
+// 背景:npm 升级 CLI 后,~/.hunter-mate/extension 仍是旧版构建(update 一致性
+// 检查只看"运行中扩展 vs 磁盘",二者同为旧版所以误判"无需 reload")。本模块以
+// CLI 包内置产物(dist/assets/extension)为上游 SSOT,按目录 checksum 比对,
+// 不一致则剪枝+复制,三处接线:
+//   1) npm postinstall(升级 CLI 即自动同步,postinstall.ts)
+//   2) update --apply / 一致性兜底(ensureRuntimeConsistency,先同步再广播 reload)
+//   3) hunter-mate install(复用同一同步逻辑,替代旧的只增不剪 copy)
+//
+// 约束:永不抛异常(调用方含 postinstall,绝不能让 npm install 失败);
+// 目标目录是软链(dev 开发模式)时跳过,不往里写。
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'node:url';
+import { findBundledAssets } from './bundled-assets.js';
+import { dirChecksum } from './utils/artifact-checksum.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** 定位 CLI 内置 extension dist(npm 包 assets 优先,monorepo 并列路径兜底) */
+export function resolveBuiltinExtensionDist() {
+    // 显式覆盖(测试夹具/应急指定),优先于一切自动探测;
+    // 设为空字符串 = 强制禁用自动探测(测试 no-bundled-assets 路径)
+    const override = process.env.HM_BUNDLED_EXTENSION_DIR;
+    if (override !== undefined)
+        return override && fs.existsSync(override) ? override : null;
+    // 优先 bundled-assets(npm 安装模式:dist/assets/extension 已存在)
+    const bundled = findBundledAssets();
+    if (bundled)
+        return bundled.extensionDir;
+    // fallback:monorepo 并列路径(老 hunter-mate 开发模式)
+    const candidates = [
+        path.resolve(__dirname, '../../extension/dist'), // src 布局: src -> packages/extension/dist
+        path.resolve(__dirname, '../../../extension/dist'), // dist 布局: dist/commands -> packages/extension/dist
+        path.resolve(__dirname, '../bundled-extension'), // bundled
+    ];
+    for (const c of candidates)
+        if (fs.existsSync(c))
+            return c;
+    return null;
+}
+/** build-info.json(FID-092 起构建注入)优先,manifest.json version 兜底 */
+function readArtifactVersion(dir) {
+    try {
+        const info = JSON.parse(fs.readFileSync(path.join(dir, 'build-info.json'), 'utf-8'));
+        if (info && typeof info.version === 'string' && info.version)
+            return info.version;
+    }
+    catch { /* 无 build-info */ }
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf-8'));
+        if (manifest && typeof manifest.version === 'string' && manifest.version)
+            return manifest.version;
+    }
+    catch { /* 无 manifest */ }
+    return '0.0.0';
+}
+export function compareExtensionArtifacts(targetDir) {
+    const target = targetDir ?? defaultTargetDir();
+    const source = resolveBuiltinExtensionDist();
+    const sourceChecksum = source ? dirChecksum(source).checksum : null;
+    const targetChecksum = fs.existsSync(target) && !isSymlink(target) ? dirChecksum(target).checksum : null;
+    return {
+        source,
+        target,
+        sourceChecksum,
+        targetChecksum,
+        sourceVersion: source ? readArtifactVersion(source) : null,
+        targetVersion: targetChecksum ? readArtifactVersion(target) : null,
+        stale: !!source && !!sourceChecksum && !!targetChecksum && sourceChecksum !== targetChecksum,
+    };
+}
+/**
+ * 同步内置扩展产物到目标目录。
+ * - source 缺失(monorepo 未构建/npm 包缺资产)→ no-op
+ * - target 缺失 → 默认 no-op(首次安装走 hunter-mate install 引导);
+ *   install 命令传 ensureTarget=true 创建
+ * - target 是软链(dev 模式)→ no-op,保护开发链
+ * - checksum 一致 → no-op;不一致 → 剪枝(删目标多余文件)+复制
+ */
+export function syncExtensionArtifacts(opts = {}) {
+    const nil = (reason) => ({ synced: false, reason, copied: 0, removed: 0 });
+    try {
+        const target = opts.target ?? defaultTargetDir();
+        const source = resolveBuiltinExtensionDist();
+        if (!source)
+            return nil('no-bundled-assets');
+        if (isSymlink(target))
+            return nil('target-is-symlink');
+        if (!fs.existsSync(target)) {
+            if (!opts.ensureTarget)
+                return nil('target-missing');
+            fs.mkdirSync(target, { recursive: true });
+        }
+        const cmp = compareExtensionArtifacts(target);
+        if (!cmp.stale) {
+            return { synced: false, reason: 'identical', copied: 0, removed: 0, fromVersion: cmp.targetVersion ?? undefined, toVersion: cmp.sourceVersion ?? undefined };
+        }
+        // 剪枝:目标中上游不存在的文件/空目录删除(纯复制会留下改名后的尸体文件)
+        let removed = 0;
+        const prune = (dst, src) => {
+            if (!fs.existsSync(dst))
+                return;
+            for (const name of fs.readdirSync(dst)) {
+                const d = path.join(dst, name);
+                const s = path.join(src, name);
+                if (!fs.existsSync(s)) {
+                    fs.rmSync(d, { recursive: true, force: true });
+                    removed++;
+                }
+                else if (fs.statSync(d).isDirectory()) {
+                    prune(d, s);
+                    if (fs.existsSync(d) && fs.readdirSync(d).length === 0)
+                        fs.rmdirSync(d);
+                }
+            }
+        };
+        prune(target, source);
+        // 复制(覆盖)
+        let copied = 0;
+        const copy = (src, dst) => {
+            const st = fs.statSync(src);
+            if (st.isDirectory()) {
+                if (!fs.existsSync(dst))
+                    fs.mkdirSync(dst, { recursive: true });
+                for (const f of fs.readdirSync(src))
+                    copy(path.join(src, f), path.join(dst, f));
+            }
+            else {
+                fs.copyFileSync(src, dst);
+                copied++;
+            }
+        };
+        copy(source, target);
+        return {
+            synced: true,
+            reason: 'stale',
+            copied,
+            removed,
+            fromVersion: cmp.targetVersion ?? undefined,
+            toVersion: cmp.sourceVersion ?? undefined,
+        };
+    }
+    catch (err) {
+        // 永不抛出(postinstall 场景绝不能让 npm install 失败)
+        return { synced: false, reason: `error: ${err.message}`, copied: 0, removed: 0 };
+    }
+}
+function defaultTargetDir() {
+    const home = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
+    return path.join(home, '.hunter-mate', 'extension');
+}
+function isSymlink(dir) {
+    try {
+        return fs.lstatSync(dir).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/i18n/locales/en-US.json

@@ -59,5 +59,21 @@
     "purge.done.next": "To re-initialize, run",
     "purge.done.nothing": "Nothing to purge",
     "login.serverOfflineSaasFallback": "Warning: local server is not running; logged in via SaaS directly. Start the server and run login again for local data operations.",
-    "login.serverOfflineReloginHint": "Note: the saved SaaS token will be rejected (401) by local server protected routes."
+    "login.serverOfflineReloginHint": "Note: the saved SaaS token will be rejected (401) by local server protected routes.",
+    "login.selfCheckOk": "Login self-check passed: protected endpoint reachable",
+    "login.selfCheckFail": "Login self-check failed: new token rejected by local server; please report with full output",
+    "login.selfCheckSkipped": "Login self-check skipped: local server unreachable; re-login once it is back",
+    "issueEnv.description": "Print the environment block needed for issue reports (CLI version / install type / git HEAD / server buildTime / OS); --format json for agents to paste directly",
+    "issueEnv.cliVersion": "CLI version",
+    "issueEnv.installType": "Install type",
+    "issueEnv.installDev": "dev (git worktree of source repo)",
+    "issueEnv.installPackage": "package (published npm build)",
+    "issueEnv.gitHead": "Code HEAD (version/buildTime do not identify code state; HEAD does)",
+    "issueEnv.gitBranch": "Branch",
+    "issueEnv.gitDirty": "uncommitted changes (dist may lag HEAD)",
+    "issueEnv.gitClean": "clean worktree",
+    "issueEnv.repoRoot": "Repo root",
+    "issueEnv.gitUnavailable": "unavailable (published package has no git info; use CLI version instead)",
+    "issueEnv.serverBuildTime": "server buildTime",
+    "issueEnv.serverNotRunning": "server not running (unavailable)"
 }

package/dist/i18n/locales/zh-CN.json

@@ -59,5 +59,21 @@
     "purge.done.next": "如需重新初始化，请运行",
     "purge.done.nothing": "无需清理",
     "login.serverOfflineSaasFallback": "警告: 本地 server 未运行,已直连 SaaS 登录;本地数据操作需启动 server 后重新 login。",
-    "login.serverOfflineReloginHint": "提示: 本次保存的是 SaaS 令牌,本地 server 的受保护路由将返回 401。"
+    "login.serverOfflineReloginHint": "提示: 本次保存的是 SaaS 令牌,本地 server 的受保护路由将返回 401。",
+    "login.selfCheckOk": "✓ 登录自检通过:受保护接口可达,search/report/job 可直接使用",
+    "login.selfCheckFail": "✗ 登录自检失败:新令牌被本地 server 拒绝,请带完整输出反馈,勿反复重试",
+    "login.selfCheckSkipped": "⚠ 登录自检跳过:本地 server 暂不可达,恢复后请重新 login",
+    "issueEnv.description": "输出提 issue 所需环境块(CLI 版本/安装方式/代码 git HEAD/server buildTime/OS),--format json 可供 agent 直接粘贴",
+    "issueEnv.cliVersion": "CLI 版本",
+    "issueEnv.installType": "安装方式",
+    "issueEnv.installDev": "dev(源码仓 git 工作区)",
+    "issueEnv.installPackage": "package(发布包)",
+    "issueEnv.gitHead": "代码 HEAD(版本号/buildTime 不说明代码状态,以 HEAD 为准)",
+    "issueEnv.gitBranch": "分支",
+    "issueEnv.gitDirty": "有未提交改动(dist 可能滞后于 HEAD)",
+    "issueEnv.gitClean": "工作区干净",
+    "issueEnv.repoRoot": "代码仓",
+    "issueEnv.gitUnavailable": "未获取(发布包无 git 信息,用 CLI 版本代替)",
+    "issueEnv.serverBuildTime": "server buildTime",
+    "issueEnv.serverNotRunning": "server 未运行(未获取)"
 }

package/dist/index.js

@@ -14,6 +14,7 @@ import { extensionCommand } from './commands/extension.js';
 import { reportCommand } from './commands/report.js';
 import { recordCommand } from './commands/record.js';
 import { cacheCommand } from './commands/cache.js';
+import { migrateDataDirCommand } from './commands/migrate.js';
 // 对应 ChromePilot 的新命令（环境管理 / 运维 / 扩展管理）
 import { initCommand } from './commands/init.js';
 import { installCommand } from './commands/install.js';
@@ -22,10 +23,18 @@ import { doctorCommand } from './commands/doctor.js';
 import { reloadCommand, openExtCommand, purgeCommand } from './commands/extras.js';
 import { recordingsCommand, adapterCommand, memoryCommand, traceCommand, autofixCommand } from './commands/ops.js';
 import { pluginCommand, skillCommand, externalCommand } from './commands/addons.js';
+import { customerCommand } from './commands/customer.js';
+import { noteCommand } from './commands/note.js';
+import { preferenceCommand } from './commands/preference.js';
+import { caseCommand } from './commands/case.js';
+import { issueEnvCommand } from './commands/issue-env.js';
 import { i18n } from './i18n/index.js';
 import { initCliLogger, flushCliLogger, getCliLogger } from './logger.js';
+import { installLocalProxyBypass } from './utils/local-http.js';
 import packageJson from '../package.json' with { type: 'json' };
 const CLI_VERSION = packageJson.version;
+// Issue #24:本地 server 探测强制绕过 http_proxy(仅 localhost/127.0.0.1,远程不动)
+installLocalProxyBypass();
 // 未捕获异常兜底(fix #27):任何命令抛出的未处理 Promise 统一友好提示 + exit 1,
 // 不再裸奔 stack 或以 exit code 0 静默结束。
 process.on('unhandledRejection', (reason) => {
@@ -81,6 +90,8 @@ program
     const name = thisCommand.name();
     if (name === 'update' || name === 'start' || name === 'stop')
         return;
+    if (name === 'migrate-data-dir')
+        return; // 迁移过程中一致性检测/自更新会干扰移动与重启
     if (name === 'doctor' || name === 'repair-linkedin-dupes')
         return;
     // fix #30: 命令以 --json(或 --format/-f json)输出时, [auto-update] 提示不得混入 stdout 的 JSON
@@ -160,4 +171,10 @@ program.addCommand(purgeCommand);
 program.addCommand(reportCommand);
 program.addCommand(recordCommand);
 program.addCommand(cacheCommand);
+program.addCommand(migrateDataDirCommand);
+program.addCommand(customerCommand);
+program.addCommand(noteCommand);
+program.addCommand(preferenceCommand);
+program.addCommand(caseCommand);
+program.addCommand(issueEnvCommand);
 program.parse();

package/dist/keychain.d.ts

@@ -1,3 +1,18 @@
-export declare function saveToken(token: string): Promise<void>;
+/**
+ * token 签发方(hmh#43):
+ * - local: 本地 server 自签 UTOKEN(设备码/邮箱代理路径),AuthMiddleware 可直接验签;
+ * - saas:  邮箱登录时本地 server 不可达,CLI 直连 SaaS 验证拿到的 token,
+ *          由 SaaS 密钥签发,本地 server 的 USER_SESSION_SECRET 验不过 → 数据面 401;
+ * - unknown: 旧版本存的裸 token(无 issuer 标记),无法区分签发方。
+ */
+export type TokenIssuer = 'local' | 'saas' | 'unknown';
+export interface TokenInfo {
+    token: string;
+    issuer: TokenIssuer;
+}
+export declare function saveToken(token: string, issuer?: TokenIssuer): Promise<void>;
+/** 只取 token 字符串(兼容全部历史调用方) */
 export declare function getToken(): Promise<string | null>;
+/** 取 token + 签发方标记(hmh#43 诊断用) */
+export declare function getTokenInfo(): Promise<TokenInfo | null>;
 export declare function deleteToken(): Promise<void>;

package/dist/keychain.js

@@ -1,30 +1,50 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { resolveDataDir } from './config.js';
 const SERVICE = 'hunter-mate';
 const ACCOUNT = 'user';
-const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const TOKEN_FILE = path.join(HOME, '.hunter-mate', 'token.json');
-function fallbackSave(token) {
-    fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+/** token 落盘文件(FID-071:随 dataDir 配置迁移;keytar 可用时不使用) */
+function tokenFile() {
+    return path.join(resolveDataDir(), 'token.json');
+}
+/** 兼容旧格式:裸 token 字符串或无 issuer 字段的 JSON */
+function parseStored(raw) {
+    if (!raw)
+        return null;
+    try {
+        const data = JSON.parse(raw);
+        if (typeof data === 'string')
+            return { token: data, issuer: 'unknown' };
+        if (data && typeof data.token === 'string') {
+            const issuer = data.issuer === 'saas' || data.issuer === 'local' ? data.issuer : 'unknown';
+            return { token: data.token, issuer };
+        }
+        return null;
+    }
+    catch {
+        return { token: raw, issuer: 'unknown' };
+    }
+}
+function fallbackSave(info) {
+    fs.mkdirSync(path.dirname(tokenFile()), { recursive: true });
     // POSIX 上 mode 0o600 强制 owner-only;Windows NTFS 上 mode bit 被忽略,
     // 由用户目录 ACL 兜底(%USERPROFILE%\.hunter-mate 默认只有当前用户可访问)。
     // 真正安全的 Windows 路径是走 keytar(Windows Credential Manager)→ setPassword。
-    fs.writeFileSync(TOKEN_FILE, JSON.stringify({ token }), { mode: 0o600 });
+    fs.writeFileSync(tokenFile(), JSON.stringify(info), { mode: 0o600 });
 }
 function fallbackGet() {
-    if (!fs.existsSync(TOKEN_FILE))
+    if (!fs.existsSync(tokenFile()))
         return null;
     try {
-        const data = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf-8'));
-        return data.token || null;
+        return parseStored(fs.readFileSync(tokenFile(), 'utf-8'));
     }
     catch {
         return null;
     }
 }
 function fallbackDelete() {
-    if (fs.existsSync(TOKEN_FILE)) {
-        fs.unlinkSync(TOKEN_FILE);
+    if (fs.existsSync(tokenFile())) {
+        fs.unlinkSync(tokenFile());
     }
 }
 async function getKeytar() {
@@ -41,26 +61,33 @@ async function getKeytar() {
         return null;
     }
 }
-export async function saveToken(token) {
+export async function saveToken(token, issuer = 'local') {
+    const payload = JSON.stringify({ token, issuer });
     const keytar = await getKeytar();
     if (keytar) {
         try {
-            await keytar.setPassword(SERVICE, ACCOUNT, token);
+            await keytar.setPassword(SERVICE, ACCOUNT, payload);
             return;
         }
         catch {
             // 降级到文件
         }
     }
-    fallbackSave(token);
+    fallbackSave({ token, issuer });
 }
+/** 只取 token 字符串(兼容全部历史调用方) */
 export async function getToken() {
+    const info = await getTokenInfo();
+    return info?.token ?? null;
+}
+/** 取 token + 签发方标记(hmh#43 诊断用) */
+export async function getTokenInfo() {
     const keytar = await getKeytar();
     if (keytar) {
         try {
-            const token = await keytar.getPassword(SERVICE, ACCOUNT);
-            if (token)
-                return token;
+            const raw = await keytar.getPassword(SERVICE, ACCOUNT);
+            if (raw)
+                return parseStored(raw);
         }
         catch {
             // 降级

package/dist/logger.js

@@ -1,6 +1,6 @@
 import { Logger, createHttpTransport } from "@chromepilot/logger-kit/client";
 import { PersistentLogQueue } from "@chromepilot/logger-kit/queue-node";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolveDataDir } from "./config.js";
 import { getToken } from "./keychain.js";
 import path from "node:path";
 let logger = null;
@@ -25,7 +25,7 @@ export function getCliLogger() {
     return logger;
 }
 function homeDir() {
-    return process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || ".";
+    return resolveDataDir();
 }
 export async function initCliLogger(options) {
     const cfg = loadConfig();

package/dist/postinstall.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/postinstall.js

@@ -0,0 +1,31 @@
+// postinstall.ts — npm install -g 后自动同步扩展产物到 ~/.hunter-mate/extension(Issue #23)
+//
+// 场景:用户 npm 升级 CLI(0.1.7 → 0.1.8+),~/.hunter-mate/extension 仍是旧版构建,
+// update 一致性检查(运行中扩展 vs 磁盘)二者同为旧版,误判"无需 reload",
+// 需手工 hunter-mate install 才刷新。postinstall 按 checksum 比对内置产物,
+// 不一致即自动同步(等价自动跑 install 的产物同步部分)。
+//
+// 红线:本脚本在 npm install 事务内执行,任何情况不得非零退出(阻断用户安装)。
+import * as fs from 'fs';
+import { syncExtensionArtifacts } from './extension-sync.js';
+function main() {
+    // 未初始化过(~/.hunter-mate/extension 不存在)→ 首次安装走 hunter-mate install 引导,不抢跑
+    const home = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE;
+    if (!home)
+        return;
+    const target = `${home}/.hunter-mate/extension`;
+    if (!fs.existsSync(target))
+        return;
+    const r = syncExtensionArtifacts();
+    if (r.synced) {
+        process.stdout.write(`[hunter-mate] 扩展产物已自动同步: ${r.fromVersion ?? '?'} → ${r.toVersion ?? '?'}`
+            + `(copied=${r.copied}, removed=${r.removed})\n`);
+        process.stdout.write('[hunter-mate] 若扩展正在运行,请执行 hunter-mate reload 或在 chrome://extensions 刷新\n');
+    }
+}
+try {
+    main();
+}
+catch {
+    // 永不阻断 npm install
+}

package/dist/updater.js

@@ -21,9 +21,9 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createCliUpdater } from '@chromepilot/kit';
 import { readInstalledVersions } from './version.js';
+import { resolveDataDir } from './config.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const ROOT = () => path.join(HOME(), '.hunter-mate');
+const ROOT = resolveDataDir;
 const CLI_PREFIX = () => path.join(ROOT(), 'cli');
 /**
  * 判定是否开发软链模式(纯函数,便于单测):

package/dist/utils/artifact-checksum.d.ts

@@ -0,0 +1,4 @@
+export declare function dirChecksum(dir: string): {
+    checksum: string;
+    latestMtimeMs: number;
+};

package/dist/utils/artifact-checksum.js

@@ -0,0 +1,40 @@
+// utils/artifact-checksum.ts — 构建产物目录指纹(sha1 + 最新 mtime)
+// 从 version.ts 抽出:postinstall/extension-sync 等轻量入口也要用,
+// 不能反向依赖 version.ts(它拉 axios/nestjs 一整条重链)。
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+export function dirChecksum(dir) {
+    const hash = createHash('sha1');
+    let latest = 0;
+    function walk(d, rel = '') {
+        try {
+            const entries = fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                const relPath = path.join(rel, entry.name);
+                const full = path.join(d, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full, relPath);
+                }
+                else if (entry.isFile() || entry.isSymbolicLink()) {
+                    try {
+                        const stat = fs.statSync(full);
+                        if (stat.mtimeMs > latest)
+                            latest = stat.mtimeMs;
+                        hash.update(relPath + '\0');
+                        const buf = fs.readFileSync(full);
+                        hash.update(buf);
+                    }
+                    catch {
+                        /* ignore unreadable */
+                    }
+                }
+            }
+        }
+        catch {
+            /* dir missing → empty */
+        }
+    }
+    walk(dir);
+    return { checksum: hash.digest('hex'), latestMtimeMs: latest };
+}

package/dist/utils/command-error.d.ts

@@ -2,8 +2,10 @@
  * 命令错误统一出口(对应 fix #18/#28):
  * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
  * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
- * - 401/403 时给出重新登录的中文提示
+ * - 401/403 时给出重新登录的中文提示;
+ *   hmh#43:token 由 SaaS 签发(本地 server 未运行时登录所致)时给出定向诊断,
+ *   不再笼统报"登录已过期"
  *
  * 调用方随后自行 process.exit(1)。
  */
-export declare function printCommandError(scope: string, err: unknown): void;
+export declare function printCommandError(scope: string, err: unknown): Promise<void>;

package/dist/utils/command-error.js

@@ -1,13 +1,16 @@
 import { getCliLogger } from '../logger.js';
+import { getTokenInfo } from '../keychain.js';
 /**
  * 命令错误统一出口(对应 fix #18/#28):
  * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
  * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
- * - 401/403 时给出重新登录的中文提示
+ * - 401/403 时给出重新登录的中文提示;
+ *   hmh#43:token 由 SaaS 签发(本地 server 未运行时登录所致)时给出定向诊断,
+ *   不再笼统报"登录已过期"
  *
  * 调用方随后自行 process.exit(1)。
  */
-export function printCommandError(scope, err) {
+export async function printCommandError(scope, err) {
     const e = err;
     const status = e?.response?.status;
     const body = e?.response?.data;
@@ -21,7 +24,20 @@ export function printCommandError(scope, err) {
     }
     if (status === 401 || status === 403) {
         console.error(`✗ ${message} (HTTP ${status})`);
-        console.error('登录已过期或无权访问,请运行 hunter-mate login 后重试');
+        let issuer = 'unknown';
+        try {
+            issuer = (await getTokenInfo())?.issuer ?? 'unknown';
+        }
+        catch {
+            // keychain 不可用时按 unknown 处理
+        }
+        if (issuer === 'saas') {
+            console.error('当前 token 由 SaaS 签发(登录时本地 server 未运行),本地 server 拒绝使用。\n' +
+                '请先启动本地 server(hunter-mate start),再重新执行 hunter-mate login。');
+        }
+        else {
+            console.error('登录已过期或无权访问,请运行 hunter-mate login 后重试');
+        }
         return;
     }
     console.error(`✗ ${scope}: ${message}${status ? ` (HTTP ${status})` : ''}`);

package/dist/utils/link.d.ts

@@ -0,0 +1,18 @@
+export type LinkKind = 'dir' | 'file';
+export interface LinkResult {
+    ok: boolean;
+    fallback?: 'copy+marker';
+    error?: string;
+}
+/**
+ * linkDev: cross-platform "point at the build artifact" dev-link helper.
+ * 实现对齐 chromepilot packages/cli/src/utils/link.ts(SSOT,同构复制)。
+ *
+ * - POSIX:  fs.symlinkSync(target, linkPath, type)
+ * - Windows directory: NTFS junction (no admin needed; cannot cross drives)。
+ *           跨盘或 junction 失败退化 copy + `<linkPath>.devlink` marker。
+ * - Windows file: copy + marker(Windows 文件软链需要 SeCreateSymbolicLink 权限,避免使用)。
+ */
+export declare function linkDev(target: string, linkPath: string, kind?: LinkKind): LinkResult;
+/** lstat 对悬空软链会抛异常而不是返回 false;包一层保证调用方拿到 boolean */
+export declare function isSymbolicLinkSafe(p: string): boolean;

package/dist/utils/link.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * linkDev: cross-platform "point at the build artifact" dev-link helper.
+ * 实现对齐 chromepilot packages/cli/src/utils/link.ts(SSOT,同构复制)。
+ *
+ * - POSIX:  fs.symlinkSync(target, linkPath, type)
+ * - Windows directory: NTFS junction (no admin needed; cannot cross drives)。
+ *           跨盘或 junction 失败退化 copy + `<linkPath>.devlink` marker。
+ * - Windows file: copy + marker(Windows 文件软链需要 SeCreateSymbolicLink 权限,避免使用)。
+ */
+export function linkDev(target, linkPath, kind = 'dir') {
+    if (fs.existsSync(linkPath)) {
+        try {
+            fs.rmSync(linkPath, { recursive: true, force: true });
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, error: `清理已存在目标失败: ${e.message}` };
+        }
+    }
+    if (process.platform !== 'win32') {
+        try {
+            fs.symlinkSync(target, linkPath, kind);
+            return { ok: true };
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, error: `symlink 失败: ${e.message}` };
+        }
+    }
+    // Windows + directory: try junction
+    if (kind === 'dir') {
+        const linkDrive = path.parse(path.resolve(linkPath)).root;
+        const targetDrive = path.parse(path.resolve(target)).root;
+        if (linkDrive && targetDrive && linkDrive !== targetDrive) {
+            try {
+                fs.cpSync(target, linkPath, { recursive: true });
+                fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+                return { ok: true, fallback: 'copy+marker' };
+            }
+            catch (err) {
+                const e = err;
+                return { ok: false, error: `junction 跨盘符退化失败: ${e.message}` };
+            }
+        }
+        try {
+            fs.symlinkSync(target, linkPath, 'junction');
+            return { ok: true };
+        }
+        catch (err) {
+            const e = err;
+            try {
+                fs.cpSync(target, linkPath, { recursive: true });
+                fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+                return { ok: true, fallback: 'copy+marker' };
+            }
+            catch (err2) {
+                const e2 = err2;
+                return { ok: false, error: `junction 与 copy 兜底均失败: ${e.message} / ${e2.message}` };
+            }
+        }
+    }
+    // Windows + file: copy + marker
+    try {
+        fs.copyFileSync(target, linkPath);
+        fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+        return { ok: true, fallback: 'copy+marker' };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, error: `copy+marker 失败: ${e.message}` };
+    }
+}
+/** lstat 对悬空软链会抛异常而不是返回 false;包一层保证调用方拿到 boolean */
+export function isSymbolicLinkSafe(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/local-http.d.ts

@@ -0,0 +1,7 @@
+export declare function isLocalServerUrl(url: string | undefined): boolean;
+/**
+ * 全局 axios 请求拦截器:调用方未显式指定 proxy 且目标是本地地址时强制 proxy:false。
+ * 在 CLI 入口(index.ts)注册一次,覆盖 status/doctor/extension 等所有探测路径;
+ * 显式传了 proxy(含已有的 proxy:false)的请求不覆盖,尊重调用方意图。
+ */
+export declare function installLocalProxyBypass(): void;