create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/api/index.ts

@@ -2,6 +2,7 @@ import request from '@/utils/request'
 
 export const EXPIRE_TIME = 60 * 10 * 1000
 
+/** 创建树形示例数据请求，使用可恢复缓存并设置十分钟有效期。 */
 export function getTree() {
   return request.Get('/xxx/xx', {
     cacheFor: {

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/hooks/chart/useEcharts.ts

@@ -8,6 +8,11 @@ import echarts from './lib'
 
 type setOptionsType = (options: EChartsOption, clear?: boolean) => void
 
+/**
+ * 管理图表的懒初始化、容器尺寸监听和组件卸载清理。
+ * @param elRef 图表容器引用，容器尚未挂载时延后初始化。
+ * @returns 设置图表配置、调整尺寸和获取实例的方法及 ECharts 模块。
+ */
 export function useECharts(
   elRef: Ref<HTMLDivElement> | Readonly<ShallowRef<HTMLDivElement | null>>,
 ) {
@@ -18,6 +23,7 @@ export function useECharts(
     chartInstance?.resize()
   }
 
+  /** 容器就绪后创建图表，并以防抖监听容器尺寸变化。 */
   const initCharts = () => {
     if (!elRef)
       return
@@ -38,6 +44,11 @@ export function useECharts(
     chartInstance = echarts.init(el)
   }
 
+  /**
+   * 确保图表已初始化后应用配置；容器未就绪时忽略本次设置。
+   * @param options ECharts 图表配置。
+   * @param clear 是否先清空已有图表，默认为 `true`。
+   */
   const setOptions: setOptionsType = (options, clear = true) => {
     if (!chartInstance) {
       initCharts()
@@ -49,13 +60,14 @@ export function useECharts(
     chartInstance?.setOption(options)
   }
 
+  /** 按需初始化并返回图表实例；容器未就绪时返回 `null`。 */
   const getInstance: () => echarts.ECharts | null = () => {
     if (!chartInstance)
       initCharts()
     return chartInstance
   }
 
-  onUnmounted(() => {
+  onUnmounted(/** 释放图表和尺寸观察器，防止卸载后继续监听。 */ () => {
     chartInstance?.dispose()
     resizeObserver?.disconnect()
     resizeObserver = undefined

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/layout/default/header/index.vue

@@ -4,6 +4,7 @@ import { useUserStoreWithOut } from '@/store/modules/user'
 const userStore = useUserStoreWithOut()
 const router = useRouter()
 
+/** 处理用户菜单；退出登录时重置用户状态并跳转到登录页。 */
 function handleMenuClick({ key }: { key: string }) {
   if (key === 'logout') {
     userStore.$reset()

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/layout/default/index.vue

@@ -14,6 +14,7 @@ const router = useRouter()
 
 const collapsed = ref(false)
 
+/** 根据当前路由匹配链计算菜单选中项。 */
 const selectedKeys = computed(() => {
   const matched = route.matched.map(item => item.name)
   return matched.filter(Boolean) as string[]
@@ -21,17 +22,19 @@ const selectedKeys = computed(() => {
 
 const openKeys = ref<string[]>([])
 
-watchEffect(() => {
+watchEffect(/** 路由变化时同步父菜单展开状态。 */ () => {
   const matched = route.matched.map(item => item.name).filter(Boolean) as string[]
   const parentKey = matched[0]
 
   openKeys.value = matched.length > 1 && parentKey !== undefined ? [parentKey] : []
 })
 
+/** 按菜单项的路由名称跳转。 */
 function handleMenuClick({ key }: { key: string }) {
   router.push({ name: key })
 }
 
+/** 将 `svg-` 前缀的菜单图标转换为图标组件，其余图标返回 `null`。 */
 function renderIcon(icon?: string) {
   if (!icon)
     return null
@@ -45,10 +48,11 @@ function renderIcon(icon?: string) {
   return null
 }
 
+/** 递归将可见路由转换为菜单项，保留标题、图标和子菜单层级。 */
 function getMenuItems(routes: MenuRouteRecordRawType[]): NonNullable<MenuProps['items']> {
   return routes
     .filter(item => !item.meta?.hideInMenu)
-    .map((item) => {
+    .map(/** 生成当前路由的菜单项，并递归构造可见子菜单。 */ (item) => {
       const hasChildren = item.children && item.children.length > 0
       const key = String(item.name ?? item.path)
       const label = item.meta?.title ?? key

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/router/guard/index.ts

@@ -2,6 +2,7 @@ import type { Router } from 'vue-router'
 
 import { createPermissionGuard } from './permissionGuard'
 
+/** 为路由实例注册应用级导航守卫。 */
 export function setupGuard(router: Router) {
   createPermissionGuard(router)
 }

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/router/guard/permissionGuard.ts

@@ -2,6 +2,7 @@ import type { Router } from 'vue-router'
 
 import NProgress from 'nprogress'
 
+/** 注册导航进度条的开始与结束钩子；当前不执行登录或权限校验。 */
 export function createPermissionGuard(router: Router) {
   router.beforeEach((_to, _from, next) => {
     NProgress.start()

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/router/index.ts

@@ -12,6 +12,7 @@ export const router = createRouter({
   scrollBehavior: () => ({ left: 0, top: 0 }),
 })
 
+/** 先注册导航守卫，再将路由安装到 Vue 应用。 */
 export function setupRouter(app: App) {
   setupGuard(router)
   app.use(router)

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/store/index.ts

@@ -6,6 +6,7 @@ import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
 export const store = createPinia()
 store.use(piniaPluginPersistedstate)
 
+/** 将已配置持久化插件的 Pinia 实例安装到 Vue 应用。 */
 export function setupStore(app: App) {
   app.use(store)
 }

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/store/modules/user.ts

@@ -12,6 +12,7 @@ export const useUserStore = defineStore('user', {
   },
 })
 
+/** 显式绑定全局 Pinia 实例，供组件外部读取或修改用户状态。 */
 export function useUserStoreWithOut() {
   return useUserStore(store)
 }

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/types/auto-import.d.ts

@@ -1,5 +1,7 @@
 /* eslint-disable */
 /* prettier-ignore */
+/* oxlint-disable */
+/* oxfmt-ignore */
 // @ts-nocheck
 // noinspection JSUnusedGlobalSymbols
 // Generated by unplugin-auto-import

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/utils/request/core/index.ts

@@ -145,16 +145,19 @@ const defaultRequestOption: BaseRequestOption<any, any, any, any> = {
   requestAdapter: adapterFetch() as AlovaRequestAdapter<any, any, any>,
 }
 
+/** 优先读取请求配置中的元数据，兼容直接挂在方法实例上的元数据。 */
 function getMethodMeta(method: unknown): RequestMeta {
   const methodRecord = method as { meta?: RequestMeta, config?: { meta?: RequestMeta } } | undefined
   return methodRecord?.config?.meta ?? methodRecord?.meta ?? {}
 }
 
+/** 获取单次请求的布尔开关；未显式设置布尔值时使用全局默认值。 */
 function getMetaFlag(meta: RequestMeta, key: keyof RequestMeta, fallback: boolean): boolean {
   const value = meta[key]
   return typeof value === 'boolean' ? value : fallback
 }
 
+/** 按数值、列表或自定义函数匹配 HTTP 状态；未配置时接受所有 2xx。 */
 function isMatchedStatus<RE>(
   status: number,
   matcher: StatusMatcher<RE> | undefined,
@@ -169,6 +172,7 @@ function isMatchedStatus<RE>(
   return Array.isArray(matcher) ? matcher.includes(status) : matcher === status
 }
 
+/** 将业务码转成字符串比较；未配置匹配列表时视为匹配。 */
 function isMatchedCode(code: unknown, matcher: CodeMatcher | undefined): boolean {
   if (!matcher?.length)
     return true
@@ -176,12 +180,14 @@ function isMatchedCode(code: unknown, matcher: CodeMatcher | undefined): boolean
   return matcher.some(item => String(item) === String(code))
 }
 
+/** 兼容适配器的 `statusCode` 与 `status` 字段，统一返回数值状态码。 */
 function getResponseStatus(response: unknown): number {
   const responseRecord = response as { status?: unknown, statusCode?: unknown }
   const status = responseRecord.statusCode ?? responseRecord.status
   return typeof status === 'number' ? status : Number(status)
 }
 
+/** 按配置字段及常见消息字段读取提示文本，无有效值时使用默认提示。 */
 function getResponseMessage(data: unknown, messageKey: string, defaultMessage: string): string {
   if (!isPlainObject(data))
     return defaultMessage
@@ -195,10 +201,15 @@ function getResponseMessage(data: unknown, messageKey: string, defaultMessage: s
   return defaultMessage
 }
 
+/** 从对象响应中读取指定业务字段，非对象响应返回 `undefined`。 */
 function getResponseField(data: unknown, key: string): unknown {
   return isPlainObject(data) ? data[key] : undefined
 }
 
+/**
+ * 根据状态码和内容类型解析 Fetch 响应，支持克隆时先克隆以保留原响应体。
+ * 无内容响应返回 `undefined`；类型未知时尝试 JSON 再尝试文本。
+ */
 async function parseFetchResponse(response: {
   status?: number
   body?: unknown
@@ -234,6 +245,7 @@ async function parseFetchResponse(response: {
   return undefined
 }
 
+/** 从 Headers 或记录对象读取响应头，兼容原键、全小写及全大写键。 */
 function getHeaderValue(
   headers: Headers | Record<string, unknown> | undefined,
   key: string,
@@ -250,6 +262,7 @@ function getHeaderValue(
   return typeof value === 'string' ? value : ''
 }
 
+/** 统一提取 Axios 的 data 或解析 Fetch 响应，无法识别的响应原样返回。 */
 async function getResponseData(response: unknown): Promise<unknown> {
   const responseRecord = response as {
     body?: unknown
@@ -272,6 +285,7 @@ async function getResponseData(response: unknown): Promise<unknown> {
   return response
 }
 
+/** 求值可异步的请求头配置，将有效值转为字符串并忽略空值。 */
 async function resolveHeaderValue(value: HeaderValue): Promise<string | undefined> {
   const resolved = typeof value === 'function' ? await value() : value
   if (resolved === null || resolved === undefined)
@@ -279,6 +293,7 @@ async function resolveHeaderValue(value: HeaderValue): Promise<string | undefine
   return String(resolved)
 }
 
+/** 将请求头写入 Headers、键值对数组或普通记录，适配不同请求适配器。 */
 function setHeader(target: unknown, key: string, value: string): void {
   if (typeof Headers !== 'undefined' && target instanceof Headers) {
     target.set(key, value)
@@ -293,12 +308,18 @@ function setHeader(target: unknown, key: string, value: string): void {
   ;(target as Record<string, string>)[key] = value
 }
 
+/** 将自定义请求选项递归合并到默认配置，补全响应解析和提示开关。 */
 function resolveConfig<RC extends object, RE, RH, SE extends StatesExport<any>>(
   option: BaseRequestOption<RC, RE, RH, SE>,
 ): ResolvedRequestOption<RC, RE, RH, SE> {
   return deepMergeObject(defaultRequestOption, option) as ResolvedRequestOption<RC, RE, RH, SE>
 }
 
+/**
+ * 创建带统一请求头、响应解包、业务码校验和消息提示的 Alova 实例。
+ * @param option 覆盖默认行为的请求、缓存和适配器配置。
+ * @returns 配置完成的请求实例，HTTP 或业务校验失败时拒绝对应请求。
+ */
 export function createInstance<
   RC extends object = FetchRequestInit,
   RE = Response,
@@ -316,6 +337,7 @@ export function createInstance<
     requestAdapter: config.requestAdapter!,
     l1Cache: config.l1Cache,
     l2Cache: config.l2Cache ?? config.storageAdapter,
+    /** 每次发送前求值公共请求头，并写入本次请求的头部容器。 */
     beforeRequest: async (method) => {
       const methodConfig = method.config as { headers?: unknown }
       const headers = methodConfig.headers ?? {}
@@ -328,6 +350,7 @@ export function createInstance<
       }
     },
     responded: {
+      /** 按请求元数据控制响应转换，校验状态与业务码并处理提示和未授权回调。 */
       onSuccess: async (response, method) => {
         const meta = getMethodMeta(method)
         const shouldTransform = getMetaFlag(meta, 'isTransformResponse', config.isTransformResponse)
@@ -384,6 +407,7 @@ export function createInstance<
 
         return responseData
       },
+      /** 按请求设置显示错误信息，并继续向调用方传播原始错误。 */
       onError: (error, method) => {
         const meta = getMethodMeta(method)
         const showError = getMetaFlag(meta, 'isShowErrorMessage', config.isShowErrorMessage)
@@ -416,6 +440,11 @@ export type DualCallInstance<
 > = RequestInstance<RC, RE, RH, SE>
   & ((option?: RequestOption<RC, RE, RH, SE>) => RequestInstance<RC, RE, RH, SE>)
 
+/**
+ * 创建同时支持直接调用 HTTP 方法和按配置派生实例的请求入口。
+ * @param baseConfig 默认实例与派生实例共用的基础配置。
+ * @returns 无参数调用时复用默认实例，传入配置时创建新实例的可调用对象。
+ */
 export function createDualCallInstance<
   RC extends object = FetchRequestInit,
   RE = Response,
@@ -423,6 +452,7 @@ export function createDualCallInstance<
   SE extends StatesExport<any> = StatesExport<any>,
 >(baseConfig: BaseRequestOption<RC, RE, RH, SE>): DualCallInstance<RC, RE, RH, SE> {
   const defaultInstance = createInstance(baseConfig)
+  /** 无覆盖配置时返回默认实例，否则基于公共配置创建独立实例。 */
   const dualInstance = ((option?: RequestOption<RC, RE, RH, SE>) => {
     if (!option)
       return defaultInstance

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/utils/request/core/utils.ts

@@ -1,4 +1,6 @@
+/** 递归合并请求配置中的对象字段；数组和普通值由目标值替换。 */
 export function deepMergeObject<T = any>(source: T, target: Partial<T>): T {
+  /** 复制并合并当前层级，目标整体为 `undefined` 时保留来源值。 */
   const merge = (src: any, tgt: any): any => {
     if (!isPlainObject(src) || !isPlainObject(tgt))
       return tgt === undefined ? src : tgt
@@ -15,16 +17,19 @@ export function deepMergeObject<T = any>(source: T, target: Partial<T>): T {
   return merge(source, target)
 }
 
+/** 根据对象标签判断是否为可按键读取和合并的对象。 */
 export function isPlainObject(data: unknown): data is Record<string, any> {
   return Object.prototype.toString.call(data) === '[object Object]'
 }
 
+/** 在当前环境支持流 API 时判断响应体是否为可读流。 */
 export function isReadableStream(data: unknown): boolean {
   if (typeof ReadableStream === 'undefined')
     return false
   return data instanceof ReadableStream
 }
 
+/** 尝试解析对象或数组形式的 JSON 字符串，其他输入或解析失败时原样返回。 */
 export function tryParseJsonString(data: unknown): unknown {
   if (typeof data !== 'string')
     return data

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/utils/request/index.ts

@@ -7,6 +7,7 @@ import { router } from '@/router'
 import { envVariables } from '../env'
 import { createDualCallInstance } from './core'
 
+/** 组合 Vue 请求适配器、业务响应字段、消息提示和未授权跳转配置。 */
 function getBaseConfig() {
   return {
     baseUrl: `/${envVariables.API_AFFIX}`,
@@ -30,6 +31,7 @@ function getBaseConfig() {
     errorMessageFunc: (msg: string) => {
       message.error(msg)
     },
+    /** 未授权时跳转登录页，并提示当前会话失效。 */
     unAuthorizedResponseFunc: () => {
       void router.push('/login')
       message.error('登录过期或未登录')

package/template-vp-monorepo-react-nestjs/apps/web-vue/src/views/example/echart/config.ts

@@ -1745,6 +1745,7 @@ export const graph = {
   ],
 }
 
+/** 根据《悲惨世界》人物关系数据生成支持漫游和邻接高亮的关系图配置。 */
 export function getOption(): EChartsOption {
   return {
     title: {

package/template-vp-monorepo-react-nestjs/apps/web-vue/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/main.ts","./src/api/index.ts","./src/hooks/chart/lib.ts","./src/hooks/chart/useecharts.ts","./src/i18n/instance.ts","./src/router/index.ts","./src/router/interface.ts","./src/router/guard/index.ts","./src/router/guard/permissionguard.ts","./src/router/modules/index.ts","./src/store/index.ts","./src/store/modules/user.ts","./src/types/antdv-next.d.ts","./src/types/auto-import.d.ts","./src/types/components.d.ts","./src/types/vite-env.d.ts","./src/utils/env.ts","./src/utils/request/index.ts","./src/utils/request/core/index.ts","./src/utils/request/core/utils.ts","./src/views/example/echart/config.ts","./src/app.vue","./src/components/icon/svg-icon.vue","./src/layout/default/index.vue","./src/layout/default/header/index.vue","./src/views/example/tree-chart.vue","./src/views/example/echart/index.vue","./src/views/home/index.vue","./src/views/login/index.vue"],"version":"6.0.3"}

package/template-vp-monorepo-react-nestjs/docker-compose.yml

@@ -34,6 +34,25 @@ services:
       - '9001:9001'
     volumes:
       - minio-data:/data
+  minio-init:
+    image: quay.io/minio/mc:latest
+    container_name: vp-minio-init
+    depends_on:
+      minio:
+        condition: service_started
+    environment:
+      MINIO_ROOT_USER: minio
+      MINIO_ROOT_PASSWORD: minio123456
+      MINIO_BUCKET: uploads
+    entrypoint: >
+      /bin/sh -c "
+      until mc alias set local http://minio:9000 $$MINIO_ROOT_USER
+      $$MINIO_ROOT_PASSWORD;
+      do sleep 1; done;
+      mc mb --ignore-existing local/$$MINIO_BUCKET;
+      mc anonymous set none local/$$MINIO_BUCKET;
+      "
+    restart: 'no'
 
 volumes:
   postgres18-data:

package/template-vp-monorepo-react-nestjs/mise.toml

@@ -1,3 +1,3 @@
 [tools]
 node = "26"
-pnpm = "11"
+pnpm = "12"

package/template-vp-monorepo-react-nestjs/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "ready": "vp check && vp run -r test && vp run -r build",
-    "dev": "pnpm run -r --stream dev",
+    "dev": "pnpm run -r --parallel --stream dev",
     "prepare": "vp config",
     "clean": "node scripts/clean.mjs",
     "reinstall": "vp install --force",
@@ -20,17 +20,5 @@
     "typescript": "catalog:",
     "vite": "catalog:",
     "vite-plus": "catalog:"
-  },
-  "devEngines": {
-    "packageManager": {
-      "name": "pnpm",
-      "version": "11.9.0",
-      "onFail": "download"
-    },
-    "runtime": {
-      "name": "node",
-      "version": ">=22.18.0",
-      "onFail": "download"
-    }
   }
 }

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/command.ts

@@ -68,6 +68,7 @@ const helpText = `用法：
   项目的 include 未匹配到任何源文件时，--clean 始终拒绝执行。
   已有翻译保持不变；新增项默认使用 key 作为翻译值。`
 
+/** 解析命令并执行词条扫描、语言包校验与可选同步，输出报告和摘要，返回命令退出码。 */
 export async function runCli(
   arguments_: readonly string[],
   environment: CliEnvironment = {},
@@ -104,7 +105,7 @@ export async function runCli(
 
   const projectEntries = selectProjects(loaded.config.projects, options.projects)
   const executions = await Promise.all(
-    projectEntries.map(async ([name, project]): Promise<ProjectExecution> => {
+    projectEntries.map(/** 扫描词条并拦截无源文件的清理。 */ async ([name, project]): Promise<ProjectExecution> => {
       const scan = await scanFiles({
         rootDir: loaded.rootDir,
         include: project.include,
@@ -203,6 +204,7 @@ export async function runCli(
   return 0
 }
 
+/** 运行命令入口，统一输出异常与用法提示；执行异常时返回退出码 2。 */
 export async function main(
   arguments_: readonly string[] = process.argv.slice(2),
   environment: CliEnvironment = {},
@@ -220,6 +222,7 @@ export async function main(
   }
 }
 
+/** 解析同步或检查命令的选项，校验必填值、未知选项和互斥组合。 */
 function parseArguments(arguments_: readonly string[]): ParsedArguments {
   const command = arguments_[0]
   if (command !== 'sync' && command !== 'check') {
@@ -285,6 +288,7 @@ function parseArguments(arguments_: readonly string[]): ParsedArguments {
   }
 }
 
+/** 读取独立命令选项后的值，并返回已消费位置；缺失值时抛出用法错误。 */
 function readOptionValue(
   arguments_: readonly string[],
   index: number,
@@ -298,6 +302,7 @@ function readOptionValue(
   return [value, index + 1]
 }
 
+/** 读取等号形式的命令选项值，空值时抛出用法错误。 */
 function readInlineOptionValue(argument: string, option: string): string {
   const value = argument.slice(option.length + 1)
   if (value.length === 0) {
@@ -307,6 +312,7 @@ function readInlineOptionValue(argument: string, option: string): string {
   return value
 }
 
+/** 按名称选择待处理项目；未指定时返回全部项目，未知项目名抛出用法错误。 */
 function selectProjects(
   projects: Readonly<Record<string, I18nProjectConfig>>,
   selectedNames: readonly string[],
@@ -315,7 +321,7 @@ function selectProjects(
     return Object.entries(projects)
   }
 
-  return selectedNames.map((name) => {
+  return selectedNames.map(/** 校验项目存在及配置有效后返回名称和配置。 */ (name) => {
     if (!Object.prototype.hasOwnProperty.call(projects, name)) {
       throw new CliUsageError(
         `Unknown project "${name}". Available projects: ${Object.keys(projects).join(', ')}.`,
@@ -331,6 +337,7 @@ function selectProjects(
   })
 }
 
+/** 将每种语言的语言包路径统一解析为相对配置根目录的绝对路径。 */
 function resolveCatalogs(
   rootDir: string,
   catalogs: Readonly<Record<string, string>>,
@@ -340,10 +347,12 @@ function resolveCatalogs(
   )
 }
 
+/** 保留绝对路径，或基于配置根目录解析相对路径。 */
 function resolveFromRoot(rootDir: string, path: string): string {
   return isAbsolute(path) ? resolve(path) : resolve(rootDir, path)
 }
 
+/** 检查语言包路径是否重复，并防止报告路径覆盖语言包或配置文件。 */
 function validateOutputPaths(
   projects: readonly ProjectCatalogs[],
   reportPath: string | undefined,
@@ -374,6 +383,7 @@ function validateOutputPaths(
   }
 }
 
+/** 允许创建报告或覆盖已有同步报告，拒绝覆盖其他已存在的文件。 */
 async function assertSafeReportTarget(reportPath: string): Promise<void> {
   let source: string
 
@@ -398,6 +408,7 @@ async function assertSafeReportTarget(reportPath: string): Promise<void> {
   }
 }
 
+/** 确认报告目标不在已扫描源码中，避免报告写入覆盖业务源码。 */
 function assertReportIsNotSourceFile(
   executions: readonly ProjectExecution[],
   reportPath: string,
@@ -417,17 +428,20 @@ function assertReportIsNotSourceFile(
   }
 }
 
+/** 规范化比较用的绝对路径，在 Windows 上忽略路径大小写。 */
 function normalizeComparablePath(path: string): string {
   const normalized = resolve(path)
   return process.platform === 'win32' ? normalized.toLowerCase() : normalized
 }
 
+/** 生成展示用的相对路径，统一使用正斜杠，根目录自身显示为句点。 */
 function toPortablePath(rootDir: string, path: string): string {
   const relativePath = relative(rootDir, path)
   const displayPath = relativePath === '' ? '.' : relativePath
   return displayPath.split(sep).join('/')
 }
 
+/** 汇总所有语言包的新增、未使用、删除和保持不变的词条数量。 */
 function summarize(files: readonly SyncFileReport[]): SummaryTotals {
   return files.reduce<SummaryTotals>(
     (totals, file) => ({
@@ -440,6 +454,7 @@ function summarize(files: readonly SyncFileReport[]): SummaryTotals {
   )
 }
 
+/** 按项目和语言输出扫描及同步结果，并展示总计与可选报告路径。 */
 function printSummary(options: {
   command: CliCommand
   dryRun: boolean
@@ -477,14 +492,17 @@ function printSummary(options: {
   }
 }
 
+/** 向标准输出写入一行命令结果。 */
 function defaultStdout(message: string): void {
   process.stdout.write(`${message}\n`)
 }
 
+/** 向标准错误输出写入一行诊断信息。 */
 function defaultStderr(message: string): void {
   process.stderr.write(`${message}\n`)
 }
 
+/** 将异常及其 cause 链递归拼接为可读的命令错误信息。 */
 function errorMessage(error: unknown): string {
   if (!(error instanceof Error)) {
     return String(error)
@@ -494,6 +512,7 @@ function errorMessage(error: unknown): string {
   return cause === undefined ? error.message : `${error.message}: ${errorMessage(cause)}`
 }
 
+/** 按命令类型与文件列表字段识别已有同步报告的基本结构。 */
 function isSyncReportLike(value: unknown): boolean {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return false
@@ -503,6 +522,7 @@ function isSyncReportLike(value: unknown): boolean {
   return (report.command === 'sync' || report.command === 'check') && Array.isArray(report.files)
 }
 
+/** 识别目标文件不存在或路径中间项不是目录的错误。 */
 function isMissingPathError(error: unknown): boolean {
   return (
     error instanceof Error &&

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/config.ts

@@ -10,6 +10,7 @@ export interface I18nConfig {
   report?: string
 }
 
+/** 原样返回国际化配置，同时保留字面量类型以提供配置校验和编辑器提示。 */
 export function defineConfig<const Config extends I18nConfig>(config: Config): Config {
   return config
 }

package/template-vp-monorepo-react-nestjs/packages/i18n/cli/src/files.ts

@@ -32,6 +32,7 @@ const defaultExcludes = [
   '**/node_modules/**',
 ]
 
+/** 按项目的包含和排除规则扫描源码，跳过含空字节的文件并收集去重词条及出现位置。 */
 export async function scanFiles(options: ScanFilesOptions): Promise<ScanFilesResult> {
   const files = await fg([...options.include], {
     absolute: true,