@longzai-intelligence-vite/plugins 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @longzai-intelligence-vite/core
 
-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.
+开发工具类项目的核心包模板，承载项目核心类型定义与配置校验能力，为 CLI 与 Dashboard 应用提供共享的类型与校验函数。
+
+定位为 dev-tool 项目模板 monorepo 的核心 packages 包，归属于 `packages/*` workspace，是 apps/cli 与 apps/dashboard 共同依赖的底层包。上游被同项目内的 cli 与 dashboard 通过 `workspace:*` 引用，自身依赖 zod 提供 Schema 校验能力，不反向依赖任何应用层包。
+
+职能上，该包通过 src/index.ts 对外导出 CoreConfig 类型与 validateConfig 校验函数：CoreConfig 定义项目核心配置的数据结构，validateConfig 基于 zod 对配置进行运行时校验。构建产物经 tsgo --build 与 resolve-aliases 处理别名解析，再由 tsdown 产出生产构建，导出路径通过 exports 字段限定为 ./dist/index.js 与对应的类型声明。
+
+实现情况为脚手架模板初始状态，package.json 的脚本（build、build:prod、typecheck、lint、test、clean 等）与 exports 声明均已就绪，zod 依赖已声明。src/index.ts 已定义导出契约，但其引用的 ./types 与 ./validate 模块文件尚未在模板中提供，需在使用模板后由开发者按导出契约补齐具体实现。

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import { PortRegistryOptions } from "@longzai-intelligence-port/registry";
+import { Plugin } from "vite";
+//#region src/dist-manifest.plugin.d.ts
+/**
+ * 产物版本清单形态，字段与升级域解析服务的 zod 校验同构
+ */
+type DistManifest = {
+  /**
+   * 包名
+   */
+  name: string;
+  /**
+   * 版本号
+   */
+  version: string;
+  /**
+   * 构建时刻的 ISO 时间戳
+   */
+  builtAt: string;
+  /**
+   * 构建时所在提交的短哈希，非 git 环境省略该键
+   */
+  gitCommit?: string;
+};
+/**
+ * 清单组装入参形态
+ */
+type ComposeDistManifestInput = {
+  /**
+   * 包定义文件路径，缺省取进程工作目录下 `package.json`
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+  /**
+   * 提交短哈希推导函数，测试可注入桩替身
+   *
+   * @default `resolveGitCommit`
+   */
+  resolveCommit?: () => string;
+};
+/**
+ * 插件选项形态
+ */
+type DistManifestPluginOptions = {
+  /**
+   * 包定义文件路径，缺省取插件工厂调用时进程工作目录下 `package.json`
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+  /**
+   * 写入产物目录的清单文件名
+   *
+   * @default `manifest.json`
+   */
+  manifestFileName?: string;
+};
+/**
+ * 推导当前提交短哈希
+ *
+ * @param cwd - git 仓库工作目录，缺省取进程工作目录
+ * @returns 七位短哈希，非 git 环境或执行失败时为空文本
+ */
+declare function resolveGitCommit(cwd?: string): string;
+/**
+ * 组装产物版本清单
+ *
+ * @remarks
+ *   字段与写盘形态对齐发布脚本的清单约定，桌面宿主的升级域解析服务按产物目录内清单文件展示当前版本与构建时间，
+ *   治理沿革自 git-reviewer 仓 issue 0048，统一方案正本见本仓 `docs/ledgers/lzi-vite-adoption/`
+ * @param input - 清单组装入参，路径与哈希推导均可注入
+ * @returns 清单对象
+ */
+declare function composeDistManifest(input?: ComposeDistManifestInput): DistManifest;
+/**
+ * 写盘入参形态
+ */
+type WriteDistManifestInput = {
+  /**
+   * 产物目录绝对路径
+   */
+  outDir: string;
+  /**
+   * 包定义文件路径
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+  /**
+   * 清单文件名
+   *
+   * @default `manifest.json`
+   */
+  manifestFileName?: string;
+};
+/**
+ * 向产物目录写入版本清单
+ *
+ * @remarks
+ *   插件 `closeBundle` 钩子的写盘正体，独立导出以便消费方与测试直接复用
+ * @param input - 写盘入参
+ */
+declare function writeDistManifest(input: WriteDistManifestInput): void;
+/**
+ * 产物版本清单写入插件工厂
+ *
+ * @remarks
+ *   构建收尾把清单写入产物目录，开发邻接解析层与打包基线均从该清单取版本与构建时间，
+ *   目录缺清单时界面将显示版本未知，产物目录经 `configResolved` 取解析后 `outDir` 以尊重命令行覆写
+ * @param options - 插件选项，包定义路径与清单文件名可覆写
+ * @returns vite 插件实例
+ */
+declare function distManifestPlugin(options?: DistManifestPluginOptions): Plugin;
+//#endregion
+//#region src/port-discovery.plugin.d.ts
+/**
+ * 插件配置选项
+ */
+type PortDiscoveryOptions = {
+  /**
+   * 要发现的后端服务名称，如 `data-server`
+   */
+  serviceName?: string;
+  /**
+   * 前端自身注册为的服务名称，如 `data-web`
+   */
+  registerAs?: string;
+  /**
+   * 等待后端服务的超时时间，单位毫秒
+   *
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * 轮询间隔，单位毫秒
+   *
+   * @default 1000
+   */
+  pollInterval?: number;
+  /**
+   * 注册表配置选项
+   */
+  registryOptions?: PortRegistryOptions;
+};
+/**
+ * 创建 vite 端口发现插件
+ *
+ * @remarks
+ *   在 dev server 启动时自动从注册表发现后端服务端口，并将前端自身端口写入注册表，
+ *   后端端口变化经注册表 `watch` 自动同步代理目标
+ * @param options - 插件配置选项
+ * @returns vite 插件实例
+ */
+declare const portDiscovery: (options?: PortDiscoveryOptions) => Plugin;
+//#endregion
+//#region src/proxy-target.utils.d.ts
+/**
+ * 解析代理目标地址
+ *
+ * @remarks
+ *   供 `vite.config.ts` 中直接调用，在配置阶段获取后端服务地址，
+ *   必须是同步函数，因为 `vite.config.ts` 是同步执行的，
+ *   注册表目录解析复用 port 域注册表的 `resolveRegistryDir` 保持单一数据源
+ * @param serviceName - 后端服务名称
+ * @param options - 注册表配置选项
+ * @returns 代理目标地址，如 `http://localhost:52341`，未找到时返回 `http://localhost:0`
+ */
+declare const resolveProxyTarget: (serviceName: string, options?: PortRegistryOptions) => string;
+//#endregion
+export { type ComposeDistManifestInput, type DistManifest, type DistManifestPluginOptions, type PortDiscoveryOptions, type WriteDistManifestInput, composeDistManifest, distManifestPlugin, portDiscovery, resolveGitCommit, resolveProxyTarget, writeDistManifest };

package/dist/index.js

@@ -0,0 +1 @@
+import{execFileSync as e}from"node:child_process";import{existsSync as t,readFileSync as n,writeFileSync as r}from"node:fs";import i,{join as a}from"node:path";import*as o from"zod";import{createPortRegistry as s,resolveRegistryDir as c}from"@longzai-intelligence-port/registry";const l=o.object({name:o.string(),version:o.string()});function u(t=process.cwd()){try{return e(`git`,[`rev-parse`,`--short`,`HEAD`],{cwd:t,encoding:`utf-8`}).trim()}catch{return``}}function d(e={}){let t=e.pkgPath??i.join(process.cwd(),`package.json`),r=l.parse(JSON.parse(n(t,`utf-8`))),a=e.resolveCommit??u,o={name:r.name,version:r.version,builtAt:(/* @__PURE__ */ new Date()).toISOString()},s=a();return s!==``&&(o.gitCommit=s),o}function f(e){let t=e.manifestFileName??`manifest.json`;r(i.join(e.outDir,t),`${JSON.stringify(d({pkgPath:e.pkgPath}),null,2)}\n`,`utf-8`)}function p(e={}){let t=e.pkgPath??i.join(process.cwd(),`package.json`),r=e.manifestFileName??`manifest.json`;l.parse(JSON.parse(n(t,`utf-8`)));let a=i.resolve(process.cwd(),`dist`);return{name:`longzai-intelligence-dist-manifest`,apply:`build`,configResolved(e){a=e.build.outDir},closeBundle(){f({outDir:a,pkgPath:t,manifestFileName:r})}}}const m=e=>{let t=e.httpServer?.address();return t&&typeof t==`object`?t.port:e.config.server.port??5173},h=e=>{let t=e.httpServer?.address();return t&&typeof t==`object`&&t.address||`localhost`};function g(e){return typeof e==`object`&&!!e}const _=(e,t)=>g(e)?e[`x-service`]===t?!0:typeof e.target==`string`?e.target.includes(`localhost:0`)||e.target.includes(`127.0.0.1:0`):!1:!1,v=(e,t,n)=>{let r=e.config.server.proxy;if(r)for(let[,i]of Object.entries(r))typeof i==`object`&&i&&`target`in i&&(String(i.target).includes(t)||_(i,t))&&(i.target=n,i.ws&&(i.target=n),e.config.logger.info(`[端口发现] 代理目标已更新: ${t} -> ${n}`))},y=async(e,t,n,r)=>{let i=Date.now();for(;Date.now()-i<n;){let n=await t.resolve(e);if(n)return n;await new Promise(e=>setTimeout(e,r))}return null},b=e=>{let t=e?.serviceName,n=e?.registerAs,r=e?.timeout??3e4,i=e?.pollInterval??1e3,a=e?.registryOptions,o=null,c=null;return{name:`longzai-intelligence-port-discovery`,apply:`serve`,configureServer:async e=>{o=s(a);let l=m(e),u=h(e);if(n&&(await o.register(n,{port:l,host:u===`::`?`localhost`:u,pid:process.pid,startedAt:Date.now()}),e.config.logger.info(`[端口发现] 前端服务已注册: ${n} -> http://${u}:${l}`)),t){e.config.logger.info(`[端口发现] 正在等待后端服务: ${t}...`);let n=await y(t,o,r,i);if(n){let r=`http://${n.host===`0.0.0.0`?`localhost`:n.host}:${n.port}`;e.config.logger.info(`[端口发现] 后端服务已发现: ${t} -> ${r}`),v(e,t,r)}else e.config.logger.warn(`[端口发现] 等待后端服务超时: ${t}，已等待 ${r}ms，代理目标可能不正确`);c=o.watch(t,n=>{if(n){let r=`http://${n.host===`0.0.0.0`?`localhost`:n.host}:${n.port}`;e.config.logger.info(`[端口发现] 后端服务端口变化: ${t} -> ${r}`),v(e,t,r)}else e.config.logger.warn(`[端口发现] 后端服务已下线: ${t}`)})}if(n){let t=e.httpServer,r=o,i=t?.close.bind(t);i&&t&&r&&(t.close=function(e){return r.deregister(n).catch(()=>{}),i(e)})}},closeBundle:async()=>{c&&=(c(),null),o&&n&&await o.deregister(n).catch(()=>{})}}},x=`http://localhost:0`,S=e=>{try{return process.kill(e,0),!0}catch{return!1}},C=(e,r)=>{let i=c(r),o=a(i,`${e}.json`);if(!t(o))return x;try{let e=n(o,`utf-8`),t=JSON.parse(e);return S(t.pid)?`http://${t.host===`0.0.0.0`?`localhost`:t.host}:${t.port}`:x}catch{return x}};export{d as composeDistManifest,p as distManifestPlugin,b as portDiscovery,u as resolveGitCommit,C as resolveProxyTarget,f as writeDistManifest};

package/lzi-builder.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@longzai-intelligence-builder/esm';
+
+/**
+ * 核心包构建配置
+ */
+export default defineConfig();

package/lzi-dev.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from '@longzai-intelligence-dev-tools/config';
+
+export default defineConfig({
+  clean: {
+    plugins: ['turbo', 'tsgo'],
+  },
+});

package/oxlint.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from '@longzai-intelligence-oxlint/presets/library';
+
+export default defineConfig();

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@longzai-intelligence-vite/plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence Vite 统一插件库",
+  "keywords": [
+    "dist-manifest",
+    "longzai-intelligence",
+    "plugins",
+    "port-discovery",
+    "vite"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production lzi-builder",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-port/registry": "0.0.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@longzai-intelligence-electron-private/web-dist-upgrade": "^0.0.3",
+    "vite": "^8.3.2"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  }
+}

package/src/__tests__/dist-manifest.plugin.test.ts

@@ -0,0 +1,173 @@
+/**
+ * 产物版本清单插件回归测试
+ *
+ * 清单形态经升级域解析服务导出的真实 zod 校验锁死，字段真源取包定义文件，
+ * 治理沿革自 git-reviewer 仓 issue 0048
+ */
+
+import { WebDistManifestSchema } from '@longzai-intelligence-electron-private/web-dist-upgrade';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  composeDistManifest,
+  distManifestPlugin,
+  writeDistManifest,
+} from '@/dist-manifest.plugin.js';
+
+/**
+ * 测试用临时目录
+ */
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'vite-plugins-manifest-test-'));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+/**
+ * 写入测试用包定义并返回其路径
+ *
+ * @param name - 包名
+ * @param version - 版本号
+ * @returns 包定义文件绝对路径
+ */
+async function writeFixturePkg(name: string, version: string): Promise<string> {
+  /**
+   * 包定义文件路径
+   */
+  const pkgPath = join(tempDir, 'package.json');
+
+  await writeFile(pkgPath, JSON.stringify({ name, version }), 'utf-8');
+  return pkgPath;
+}
+
+describe('composeDistManifest', () => {
+  test('清单通过升级域解析服务的 zod 校验且字段取自包定义', async () => {
+    /**
+     * 包定义文件路径
+     */
+    const pkgPath = await writeFixturePkg('@longzai-intelligence-vite/plugins', '0.0.0');
+
+    /**
+     * 带提交短哈希的清单
+     */
+    const manifest = composeDistManifest({ pkgPath, resolveCommit: () => '947dd0f' });
+
+    expect(manifest.name).toBe('@longzai-intelligence-vite/plugins');
+    expect(manifest.version).toBe('0.0.0');
+    expect(manifest.gitCommit).toBe('947dd0f');
+    expect(manifest.builtAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    expect(Number.isNaN(Date.parse(manifest.builtAt))).toBe(false);
+    expect(WebDistManifestSchema.safeParse(manifest).success).toBe(true);
+  });
+
+  test('提交短哈希推导失败时省略该键且清单仍通过校验', async () => {
+    /**
+     * 包定义文件路径
+     */
+    const pkgPath = await writeFixturePkg('@longzai-intelligence-vite/plugins', '0.0.0');
+
+    /**
+     * 无提交短哈希的清单
+     */
+    const manifest = composeDistManifest({ pkgPath, resolveCommit: () => '' });
+
+    expect(Object.hasOwn(manifest, 'gitCommit')).toBe(false);
+    expect(WebDistManifestSchema.safeParse(manifest).success).toBe(true);
+  });
+
+  test('包定义路径缺省取进程工作目录下 package.json', async () => {
+    /**
+     * 原工作目录
+     */
+    const originalCwd = process.cwd();
+
+    process.chdir(tempDir);
+    try {
+      await writeFixturePkg('@demo/app', '1.2.3');
+
+      /**
+       * 以缺省路径组装的清单
+       */
+      const manifest = composeDistManifest({ resolveCommit: () => 'abc1234' });
+
+      expect(manifest.name).toBe('@demo/app');
+      expect(manifest.version).toBe('1.2.3');
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});
+
+describe('distManifestPlugin', () => {
+  test('插件名与作用阶段正确且钩子齐备', async () => {
+    /**
+     * 包定义文件路径
+     */
+    const pkgPath = await writeFixturePkg('@demo/app', '1.2.3');
+
+    /**
+     * 插件实例
+     */
+    const plugin = distManifestPlugin({ pkgPath });
+
+    expect(plugin.name).toBe('longzai-intelligence-dist-manifest');
+    expect(plugin.apply).toBe('build');
+    expect(typeof plugin.configResolved).toBe('function');
+    expect(typeof plugin.closeBundle).toBe('function');
+  });
+});
+
+describe('writeDistManifest', () => {
+  test('向产物目录写入指定文件名的清单', async () => {
+    /**
+     * 包定义文件路径
+     */
+    const pkgPath = await writeFixturePkg('@demo/app', '1.2.3');
+
+    /**
+     * 产物目录
+     */
+    const outDir = join(tempDir, 'dist');
+    await mkdir(outDir, { recursive: true });
+
+    writeDistManifest({ outDir, pkgPath, manifestFileName: 'version.json' });
+
+    /**
+     * 写盘后的清单内容
+     */
+    const written = await Bun.file(join(outDir, 'version.json')).text();
+
+    expect(JSON.parse(written).name).toBe('@demo/app');
+    expect(JSON.parse(written).version).toBe('1.2.3');
+    expect(written.endsWith('\n')).toBe(true);
+  });
+
+  test('写盘清单通过升级域解析服务的 zod 校验', async () => {
+    /**
+     * 包定义文件路径
+     */
+    const pkgPath = await writeFixturePkg('@demo/app', '1.2.3');
+
+    /**
+     * 产物目录
+     */
+    const outDir = join(tempDir, 'dist');
+    await mkdir(outDir, { recursive: true });
+
+    writeDistManifest({ outDir, pkgPath });
+
+    /**
+     * 写盘后的清单内容
+     */
+    const written = await Bun.file(join(outDir, 'manifest.json')).text();
+
+    expect(WebDistManifestSchema.safeParse(JSON.parse(written)).success).toBe(true);
+  });
+});

package/src/__tests__/port-discovery.plugin.test.ts

@@ -0,0 +1,223 @@
+/**
+ * 端口发现插件与代理目标解析回归测试
+ *
+ * 自 dev-tools 仓 `packages/vite-plugin` 承接迁入时的同构用例
+ */
+
+import type { PortDiscoveryOptions } from '@/port-discovery.plugin.js';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { portDiscovery } from '@/port-discovery.plugin.js';
+import { resolveProxyTarget } from '@/proxy-target.utils.js';
+
+/**
+ * 测试用临时注册表目录
+ */
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'vite-plugins-port-test-'));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe('portDiscovery', () => {
+  test('插件名称正确', () => {
+    /**
+     * 插件实例
+     */
+    const plugin = portDiscovery();
+    expect(plugin.name).toBe('longzai-intelligence-port-discovery');
+  });
+
+  test('apply 属性为 serve', () => {
+    /**
+     * 插件实例
+     */
+    const plugin = portDiscovery();
+    expect(plugin.apply).toBe('serve');
+  });
+
+  test('完整配置时创建插件不报错', () => {
+    /**
+     * 插件配置
+     */
+    const options: PortDiscoveryOptions = {
+      serviceName: 'data-server',
+      registerAs: 'data-web',
+      timeout: 5000,
+      pollInterval: 500,
+      registryOptions: { registryDir: tempDir },
+    };
+
+    /**
+     * 插件实例
+     */
+    const plugin = portDiscovery(options);
+    expect(plugin.name).toBe('longzai-intelligence-port-discovery');
+    expect(plugin.apply).toBe('serve');
+  });
+});
+
+describe('resolveProxyTarget', () => {
+  test('能读取已注册的服务', async () => {
+    /**
+     * 服务注册信息
+     */
+    const serviceInfo = {
+      name: 'data-server',
+      port: 52341,
+      host: 'localhost',
+      pid: process.pid,
+      startedAt: Date.now(),
+    };
+
+    /**
+     * 写入注册文件
+     */
+    await mkdir(tempDir, { recursive: true });
+    await writeFile(
+      join(tempDir, 'data-server.json'),
+      JSON.stringify(serviceInfo, null, 2),
+      'utf-8',
+    );
+
+    /**
+     * 解析代理目标
+     */
+    const target = resolveProxyTarget('data-server', { registryDir: tempDir });
+    expect(target).toBe('http://localhost:52341');
+  });
+
+  test('未注册时返回占位符', () => {
+    /**
+     * 解析不存在的服务
+     */
+    const target = resolveProxyTarget('non-existent', { registryDir: tempDir });
+    expect(target).toBe('http://localhost:0');
+  });
+
+  test('僵尸文件返回占位符', async () => {
+    /**
+     * 使用不存在的 pid 模拟僵尸文件
+     */
+    const zombieInfo = {
+      name: 'zombie-server',
+      port: 9999,
+      host: 'localhost',
+      pid: 99999999,
+      startedAt: Date.now(),
+    };
+
+    /**
+     * 写入僵尸注册文件
+     */
+    await mkdir(tempDir, { recursive: true });
+    await writeFile(
+      join(tempDir, 'zombie-server.json'),
+      JSON.stringify(zombieInfo, null, 2),
+      'utf-8',
+    );
+
+    /**
+     * 解析僵尸服务应返回占位符
+     */
+    const target = resolveProxyTarget('zombie-server', { registryDir: tempDir });
+    expect(target).toBe('http://localhost:0');
+  });
+
+  test('0.0.0.0 主机替换为 localhost', async () => {
+    /**
+     * 使用 0.0.0.0 主机的服务
+     */
+    const serviceInfo = {
+      name: 'gateway-server',
+      port: 3000,
+      host: '0.0.0.0',
+      pid: process.pid,
+      startedAt: Date.now(),
+    };
+
+    /**
+     * 写入注册文件
+     */
+    await mkdir(tempDir, { recursive: true });
+    await writeFile(
+      join(tempDir, 'gateway-server.json'),
+      JSON.stringify(serviceInfo, null, 2),
+      'utf-8',
+    );
+
+    /**
+     * 解析代理目标
+     */
+    const target = resolveProxyTarget('gateway-server', { registryDir: tempDir });
+    expect(target).toBe('http://localhost:3000');
+  });
+
+  test('损坏的 JSON 文件返回占位符', async () => {
+    /**
+     * 写入损坏的 JSON 文件
+     */
+    await mkdir(tempDir, { recursive: true });
+    await writeFile(join(tempDir, 'broken-server.json'), 'invalid json content', 'utf-8');
+
+    /**
+     * 解析损坏文件应返回占位符
+     */
+    const target = resolveProxyTarget('broken-server', { registryDir: tempDir });
+    expect(target).toBe('http://localhost:0');
+  });
+
+  test('DEV_PORTS_DIR 环境变量覆盖注册表目录', async () => {
+    /**
+     * 环境变量指定的临时目录
+     */
+    const envDir = await mkdtemp(join(tmpdir(), 'env-vite-plugins-test-'));
+
+    /**
+     * 服务注册信息
+     */
+    const serviceInfo = {
+      name: 'env-server',
+      port: 5555,
+      host: 'localhost',
+      pid: process.pid,
+      startedAt: Date.now(),
+    };
+
+    /**
+     * 写入注册文件
+     */
+    await writeFile(join(envDir, 'env-server.json'), JSON.stringify(serviceInfo, null, 2), 'utf-8');
+
+    /**
+     * 保存并设置环境变量
+     */
+    const originalValue = process.env.DEV_PORTS_DIR;
+    process.env.DEV_PORTS_DIR = envDir;
+
+    /**
+     * 解析代理目标
+     */
+    const target = resolveProxyTarget('env-server');
+    expect(target).toBe('http://localhost:5555');
+
+    /**
+     * 恢复环境变量
+     */
+    if (originalValue) {
+      process.env.DEV_PORTS_DIR = originalValue;
+    } else {
+      delete process.env.DEV_PORTS_DIR;
+    }
+
+    await rm(envDir, { recursive: true, force: true });
+  });
+});