listpage_cli 0.0.297 → 0.0.299

package/bin/adapters/cli-interaction.js

@@ -134,18 +134,46 @@ async function askOverwrite() {
     }
     return (0, interaction_result_1.interactionValue)(result.value.ok);
 }
+const HELP_ANSI = {
+    reset: "\u001b[0m",
+    dim: "\u001b[2m",
+    cyan: "\u001b[36m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+};
+const HELP_USE_COLOR = process.env.NO_COLOR === undefined;
+function helpColor(text, color) {
+    if (!HELP_USE_COLOR) {
+        return text;
+    }
+    return `${HELP_ANSI[color]}${text}${HELP_ANSI.reset}`;
+}
 function printHelp() {
     const h = [
-        "用法: listpage_cli init",
-        "说明: 进入中文引导式交互，按提示填写即可",
-        "用法: listpage_cli install-skill [skillName] [--project]",
-        "说明: 安装技能到 Cursor。默认 skillName 为 test，安装到当前命令执行目录的 .cursor/skills/",
-        "用法: listpage_cli build-project",
-        "说明: 非交互校验当前目录是否为有效项目根（需存在 listpage.config.json）",
-        "用法: listpage_cli release-project [tag] [--profile dev] [--platform linux/amd64] [--env KEY=VALUE]",
-        "说明: 先校验 .listpage/output 产物，再按 login/build/tag/push 执行 Docker 发布；参数优先级: CLI > profile > base",
-        "用法: listpage_cli deploy-project [tag] [--profile dev] [--platform linux/amd64] [--env KEY=VALUE]",
-        "说明: 使用 docker.remote + docker.container 执行部署，支持 ports[] 与 envFile/env 合并；参数优先级: CLI > profile > base",
+        helpColor("listpage_cli 命令说明", "cyan"),
+        "",
+        `  ${helpColor("init", "green")}`,
+        `    用法: ${helpColor("listpage_cli init", "dim")}`,
+        "    说明: 进入中文引导式交互，按提示填写即可",
+        "",
+        `  ${helpColor("install-skill", "green")}`,
+        `    用法: ${helpColor("listpage_cli install-skill [skillName] [--project]", "dim")}`,
+        "    说明: 安装技能到 Cursor；默认 skillName 为 test，安装到当前命令执行目录的 .cursor/skills/",
+        "",
+        `  ${helpColor("build-project", "green")}`,
+        `    用法: ${helpColor("listpage_cli build-project", "dim")}`,
+        "    说明: 非交互校验当前目录是否为有效项目根（需存在 listpage.config.json）",
+        "",
+        `  ${helpColor("release-project", "green")}`,
+        `    用法: ${helpColor("listpage_cli release-project [tag] [--profile dev] [--platform linux/amd64] [--env KEY=VALUE]", "dim")}`,
+        "    说明: 先校验 .listpage/output 产物，再按 login/build/tag/push 执行 Docker 发布",
+        `    备注: ${helpColor("参数优先级为 CLI > profile > base", "yellow")}`,
+        "",
+        `  ${helpColor("deploy-project", "green")}`,
+        `    用法: ${helpColor("listpage_cli deploy-project [tag] [--profile dev] [--platform linux/amd64] [--env KEY=VALUE] [--skip-image]", "dim")}`,
+        "    说明: 使用 docker.remote + docker.container 执行部署，支持 ports[] 与 envFile/env 合并",
+        `    备注: ${helpColor("默认会清理并拉取镜像；传入 --skip-image 时只执行容器相关步骤（假定镜像已是最新且已存在）", "yellow")}`,
+        `          ${helpColor("参数优先级为 CLI > profile > base", "yellow")}`,
     ].join("\n");
     console.log(h);
 }

package/bin/app/parse-args.js

@@ -46,10 +46,12 @@ function parseCommandOptions(rawArgs) {
     const platform = readSingleOption(args, "platform");
     const envEntries = readMultiOption(args, "env");
     const env = parseEnvEntries(envEntries);
+    const skipImage = args.includes("--skip-image");
     return {
         profile,
         platform,
         env: Object.keys(env).length > 0 ? env : undefined,
+        skipImage: skipImage || undefined,
     };
 }
 function parseCommandPositionals(rawArgs) {

package/bin/commands/deploy-project-command.js

@@ -19,6 +19,7 @@ function createDeployProjectCommandHandler(deps) {
         return (0, deploy_project_service_1.runDeployProjectFlow)({
             ...deps,
             cliOverrides,
+            skipImage: options.skipImage === true,
         });
     };
 }

package/bin/services/deploy-project-service.js

@@ -90,6 +90,7 @@ async function runDeployProjectFlow(deps) {
         executionInput,
         resolve: deps.fs.resolve,
         readText: deps.fs.readText,
+        skipImage: deps.skipImage === true,
     });
 }
 function resolveRuntimeConfig(config, cliOverrides) {
@@ -142,28 +143,6 @@ async function runDockerDeploy(input) {
     const { client, executionInput } = input;
     const remoteImage = executionInput.remoteImage;
     logDeployStep("run", `开始部署镜像: ${remoteImage}`);
-    try {
-        logDeployStep("run", `检查本地镜像是否存在: ${remoteImage}`);
-        const exists = await client.imageExists(remoteImage);
-        logDeployStep("run", `本地镜像检查结果: exists=${exists ? "yes" : "no"}`);
-        if (exists) {
-            logDeployStep("run", `删除旧镜像: ${remoteImage}`);
-            await client.removeImage(remoteImage);
-            logDeployStep("run", `旧镜像删除完成: ${remoteImage}`);
-        }
-    }
-    catch (error) {
-        return (0, command_result_1.commandError)(`[${DEPLOY_STAGE}][run] 清理镜像缓存失败: ${toErrorMessage(error)}`, command_result_1.COMMAND_ERROR_CODES.executionFailed, 1);
-    }
-    try {
-        const auth = buildPullAuth(executionInput.docker);
-        logDeployStep("run", `开始拉取镜像: ${remoteImage} (auth=${auth ? "yes" : "no"})`);
-        await client.pullImage(remoteImage, auth);
-        logDeployStep("run", `镜像拉取完成: ${remoteImage}`);
-    }
-    catch (error) {
-        return (0, command_result_1.commandError)(`[${DEPLOY_STAGE}][run] 拉取镜像失败: ${toErrorMessage(error)}`, command_result_1.COMMAND_ERROR_CODES.executionFailed, 1);
-    }
     try {
         logDeployStep("run", `检查已有容器: ${executionInput.runtime.containerName}`);
         const existingContainerId = await client.findContainerIdByName(executionInput.runtime.containerName);
@@ -179,6 +158,33 @@ async function runDockerDeploy(input) {
     catch (error) {
         return (0, command_result_1.commandError)(`[${DEPLOY_STAGE}][run] 替换容器失败: ${toErrorMessage(error)}`, command_result_1.COMMAND_ERROR_CODES.executionFailed, 1);
     }
+    if (input.skipImage !== true) {
+        try {
+            logDeployStep("run", `检查本地镜像是否存在: ${remoteImage}`);
+            const exists = await client.imageExists(remoteImage);
+            logDeployStep("run", `本地镜像检查结果: exists=${exists ? "yes" : "no"}`);
+            if (exists) {
+                logDeployStep("run", `删除旧镜像: ${remoteImage}`);
+                await client.removeImage(remoteImage);
+                logDeployStep("run", `旧镜像删除完成: ${remoteImage}`);
+            }
+        }
+        catch (error) {
+            return (0, command_result_1.commandError)(`[${DEPLOY_STAGE}][run] 清理镜像缓存失败: ${toErrorMessage(error)}`, command_result_1.COMMAND_ERROR_CODES.executionFailed, 1);
+        }
+        try {
+            const auth = buildPullAuth(executionInput.docker);
+            logDeployStep("run", `开始拉取镜像: ${remoteImage} (auth=${auth ? "yes" : "no"})`);
+            await client.pullImage(remoteImage, auth);
+            logDeployStep("run", `镜像拉取完成: ${remoteImage}`);
+        }
+        catch (error) {
+            return (0, command_result_1.commandError)(`[${DEPLOY_STAGE}][run] 拉取镜像失败: ${toErrorMessage(error)}`, command_result_1.COMMAND_ERROR_CODES.executionFailed, 1);
+        }
+    }
+    else {
+        logDeployStep("run", `跳过镜像处理: 按照 --skip-image 假定镜像已存在且为最新`);
+    }
     let createContainerInput;
     try {
         createContainerInput = (0, dockerode_client_1.toRuntimeContainerInput)({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listpage_cli",
-  "version": "0.0.297",
+  "version": "0.0.299",
   "private": false,
   "bin": {
     "listpage_cli": "bin/cli.js"

package/templates/backend-template/package.json.tmpl

@@ -25,7 +25,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "~0.14.2",
     "rxjs": "^7.8.1",
-    "listpage-next-nest": "~0.0.297"
+    "listpage-next-nest": "~0.0.299"
   },
   "devDependencies": {
     "@nestjs/schematics": "^11.0.0",

package/templates/frontend-template/package.json.tmpl

@@ -12,7 +12,7 @@
   "dependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "listpage-next": "~0.0.297",
+    "listpage-next": "~0.0.299",
     "react-router-dom": ">=6.0.0",
     "@ant-design/v5-patch-for-react-19": "~1.0.3",
     "ahooks": "^3.9.5",
@@ -23,7 +23,7 @@
     "styled-components": "^6.1.19",
     "mobx": "~6.15.0",
     "@ant-design/icons": "~6.0.2",
-    "listpage-components": "~0.0.297",
+    "listpage-components": "~0.0.299",
     "lucide-react": "~0.575.0"
     "mobx-react-lite": "~4.1.1"
   },

package/templates/skills-template/listpage-http/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: listpage-http
+description: 使用 listpage-http 在前端项目中接管所有 HTTP 请求，统一通过 src/api 目录的 request-config 与 client 调用。Use when user mentions listpage-http, request-config, api client or统一 HTTP 请求管理.
+---
+
+# listpage-http 使用技能
+
+详细 API 说明与代码示例见 [api.md](api.md)、[examples.md](examples.md)。
+
+## 总体目标
+
+在新项目中用 `listpage-http` 接管所有 HTTP 请求，形成统一、可追踪的接口层：
+
+- 所有后端接口 **必须在一个 request-config 映射表中集中注册**。
+- 所有业务代码 **只能通过统一的 client 调用接口**。
+- 每个业务模块在 `src/api` 下有对应的「类型文件」，只负责声明请求/响应类型。
+- **接口报错已由此 API 层接管**（通过 `onError`、未授权跳转等统一处理），业务层**不需要也不应再**在调用处捕获接口错误（如对 `api.xxx.yyy()` 包一层 try/catch 专门处理接口失败）。
+
+## 目录规范
+
+推荐统一目录结构（可按项目实际略调，但语义不变）：
+
+```
+src/
+  api/
+    request-config.ts     # 用 defineEndpoint 注册所有接口
+    index.ts              # createApiClient，默认导出 client
+    user.ts               # user 模块：只放接口的 Req/Res 类型
+    order.ts              # 其他模块同理……
+```
+
+规范要求：
+
+1. **`src/api/*.ts`（如 `user.ts`）**
+   - 只定义对应模块的 **请求体类型 (ReqXXX)** 和 **响应数据类型 (ResXXX)**。
+   - 如果类型过多，可以拆分到子目录，最终由该模块 `index.ts` 统一导出类型。
+   - 不在这里直接发请求，不引入 `createApiClient`。
+
+2. **`src/api/request-config.ts`**
+   - 作为**唯一的接口映射表**。
+   - 使用 `defineEndpoint<Req, Res>()` 注册所有后端接口。
+   - 新增接口时，必须先在这里补配置，保证接口「一表可查」。
+
+3. **`src/api/index.ts`**
+   - 使用 `createApiClient(requestConfig, clientOptions)` 创建客户端。
+   - **默认导出 client**，供业务代码通过 `import api from '@/api'` 使用。
+   - 负责配置 baseURL、tokenKey、默认超时、成功码、未授权处理、**统一错误处理（onError）**等；接口报错由此层统一接管，业务层无需再捕获。
+
+## 使用流程（6 步）
+
+```
+Task Progress:
+- [ ] 步骤 1：为模块创建类型文件（如 src/api/user.ts），定义 ReqXXX / ResXXX
+- [ ] 步骤 2：在 src/api/request-config.ts 中用 defineEndpoint 注册接口
+- [ ] 步骤 3：在 src/api/index.ts 中用 createApiClient 创建并导出 client
+- [ ] 步骤 4：在 service / hooks 中通过 api.xxx.yyy 调用接口
+- [ ] 步骤 5：禁止业务代码直接使用 fetch / axios 等绕过 api 目录
+- [ ] 步骤 6：新增接口时，始终遵循「类型 → request-config → 业务调用」顺序
+```
+
+## 命名与模块约定
+
+- **模块名**：`requestConfig` 中一级 key 建议与模块文件名一致，如 `user`、`order`。
+- **方法名**：使用动词短语小驼峰，如 `login`、`list`、`detail`、`create`、`update`、`remove`。
+- **类型命名**：
+  - 请求体：`ReqLogin`、`ReqUserList` 等。
+  - 响应数据：`ResLogin`、`ResUserList` 等。
+- **响应 envelope**：后端返回一般为 `{ code, message, data }`，`listpage-http` 用 `ApiEnvelope<T>` 表示，内部会按 `successCodes`、`unauthorizedCodes` 解析。

package/templates/skills-template/listpage-http/api.md

@@ -0,0 +1,102 @@
+# API（listpage-http）
+
+基于浏览器原生 `fetch` 的配置驱动 HTTP 客户端，统一处理 JSON 请求与 SSE 流。
+
+## 核心类型与方法
+
+来自 `listpage-http` 的主要导出（见 `src/index.ts`）：
+
+- **类型**
+  - `ClientOptions`：创建客户端时的全局配置。
+  - `RequestOptions`：单次调用时的可选配置（超时、headers、缓存等）。
+  - `EndpointConfig<Req, Res>`：单个接口配置泛型。
+  - `EndpointMode`：`"json" | "upload" | "download" | "sse"`。
+  - `ApiEnvelope<T>`：后端 `{ code, message, data }` 统一模型。
+- **配置工具**
+  - `defineEndpoint<Req, Res>(config: EndpointConfig<Req, Res>)`：声明一个接口。
+- **客户端**
+  - `createApiClient<Cfg>(config: Cfg, clientOptions: ClientOptions): ApiClient<Cfg>`
+  - `ApiClient<Cfg>`：根据 `requestConfig` 推导出的类型安全客户端。
+
+### EndpointConfig<Req, Res>
+
+```ts
+export type EndpointConfig<Req, Res> = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  defaultOptions?: RequestOptions;
+  type?: "http" | "sse";
+  mode?: "json" | "upload" | "download" | "sse";
+  authRequired?: boolean; // 默认 true
+};
+```
+
+### defineEndpoint
+
+```ts
+export function defineEndpoint<Req, Res>(
+  config: EndpointConfig<Req, Res>
+): EndpointConfig<Req, Res>;
+```
+
+用途：
+
+- 声明接口的 HTTP 方法、路径、是否 SSE、是否需要鉴权。
+- 绑定请求泛型 `Req` 与响应泛型 `Res`，后续通过 `ApiClient` 自动推导。
+
+### ClientOptions
+
+```ts
+export interface ClientOptions {
+  baseURL: string;
+  tokenKey?: string;
+  defaultTimeout?: number;
+  defaultCacheTime?: number;
+  defaultHeaders?: Record<string, string>;
+  successCodes?: number[];
+  unauthorizedCodes?: number[];
+  unauthorizedRedirectPath?: string;
+  server?: {
+    protocol?: string;
+    host?: string;
+    port?: number;
+    publicPath?: string;
+  };
+  onError?: (code: number, message: string) => void;
+}
+```
+
+说明：
+
+- `baseURL`：通常指 `/api/v1` 这一级；也可以配合 `server` 决定完整 URL。
+- `tokenKey`：约定从何处读取 Token（如 localStorage key），具体读取逻辑视实现而定。
+- `successCodes`：哪些业务 code 视为成功（例如 `[20000, 200]`）。
+- `unauthorizedCodes`：未授权业务码（如 `[401, 403]`），可配合跳登录。
+- `onError`：统一错误处理函数，网络错误、4xx/5xx 业务错误都会透传进来。
+
+### RequestOptions
+
+```ts
+export interface RequestOptions {
+  timeout?: number; // 单次调用超时
+  headers?: Record<string, string>;
+  cache?: {
+    key?: string;
+    time?: number; // 缓存时间(ms)
+  };
+}
+```
+
+说明：
+
+- 若不配 `timeout`，会 fallback 到 `ClientOptions.defaultTimeout`。
+- 若不配 `cache`，则该次请求不走缓存逻辑。
+
+### ApiClient<Cfg>
+
+由 `createApiClient` 根据 `requestConfig` 自动推导：
+
+- 普通 HTTP 接口：`(params: Req, options?: RequestOptions) => Promise<Res>`
+- SSE 接口：`(params: Req, options?: RequestOptions) => Promise<ReadableStream<any>>`
+
+业务调用时通过 `api.{module}.{fn}(params, options?)` 即可，类型由 `Req`/`Res` 自动推断。

package/templates/skills-template/listpage-http/examples.md

@@ -0,0 +1,167 @@
+# listpage-http 示例
+
+## 1. 定义 user 模块类型（`src/api/user.ts`）
+
+```ts
+export interface ReqLogin {
+  email: string;
+  password: string;
+}
+
+export interface ResLogin {
+  token: string;
+}
+```
+
+> 只放类型，不在这里发请求。
+
+---
+
+## 2. 集中注册接口（`src/api/request-config.ts`）
+
+```ts
+import { defineEndpoint } from "listpage-http";
+import type { ReqLogin, ResLogin } from "./user";
+
+export const requestConfig = {
+  user: {
+    login: defineEndpoint<ReqLogin, ResLogin>({
+      method: "POST",
+      path: "/auth/login",
+      defaultOptions: {
+        timeout: 10_000,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+      // type: "http",      // 默认 http，可省略
+      // mode: "json",      // 默认 json，可省略
+      // authRequired: false, // 如登录接口可显式关闭鉴权
+    }),
+  },
+} as const;
+
+export type RequestConfig = typeof requestConfig;
+```
+
+---
+
+## 3. 创建并导出 client（`src/api/index.ts`）
+
+```ts
+import { createApiClient } from "listpage-http";
+import { requestConfig, type RequestConfig } from "./request-config";
+
+const isDev = process.env.NODE_ENV === "development";
+
+const api = createApiClient<RequestConfig>(requestConfig, {
+  baseURL: isDev ? "http://localhost:3000/api/v1" : "/api/v1",
+  tokenKey: "AUTH_TOKEN",
+  defaultTimeout: 10_000,
+  defaultCacheTime: 5_000,
+  successCodes: [20000, 200],
+  unauthorizedCodes: [401, 403],
+  unauthorizedRedirectPath: "/login",
+  onError: (code, message) => {
+    // 统一错误处理：可根据 code 决定弹 Toast、跳转登录等
+    console.error("[API Error]", code, message);
+  },
+});
+
+export default api;
+```
+
+---
+
+## 4. 在 service 中调用（推荐，不直接在组件里写细节）
+
+```ts
+// src/services/auth.ts
+import api from "@/api";
+import type { ReqLogin, ResLogin } from "@/api/user";
+
+export async function login(values: ReqLogin): Promise<ResLogin> {
+  const data = await api.user.login(values, {
+    timeout: 5_000, // 可选：覆盖默认超时
+  });
+  return data;
+}
+```
+
+---
+
+## 5. 在组件中使用
+
+接口报错已由 api 层（`onError`）统一处理，业务层**不需要**对 `api` 调用再包 try/catch 来弹错误提示。
+
+```tsx
+import { useState } from "react";
+import { message } from "antd";
+import { login } from "@/services/auth";
+
+export function LoginForm() {
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (values: { email: string; password: string }) => {
+    setLoading(true);
+    await login(values);
+    message.success("登录成功");
+    // TODO: 写入 token / 跳转
+    setLoading(false);
+  };
+
+  // 此处省略表单 JSX，只保留调用方式示例
+  return null;
+}
+```
+
+---
+
+## 6. SSE 示例（可选）
+
+```ts
+// 在 request-config 中配置 SSE 接口
+import { defineEndpoint } from "listpage-http";
+
+export const requestConfig = {
+  agent: {
+    generateCode: defineEndpoint<{ id: string }, void>({
+      method: "POST",
+      path: "/agent/generate-code",
+      type: "sse",
+      mode: "sse",
+      defaultOptions: {
+        timeout: 3_000, // 建连超时
+      },
+    }),
+  },
+} as const;
+```
+
+```ts
+// 调用方式
+import api from "@/api";
+
+async function startSse(id: string) {
+  const stream = await api.agent.generateCode({ id });
+
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const chunk = decoder.decode(value, { stream: true });
+    console.log("SSE chunk:", chunk);
+  }
+}
+```
+
+---
+
+## 7. 新增接口 Checklist
+
+1. 在对应模块类型文件（如 `src/api/order.ts`）中添加 `ReqOrderList` / `ResOrderList` 等类型。
+2. 在 `src/api/request-config.ts` 中为该模块新增一个 `defineEndpoint`（例如 `order.list`）。
+3. 在 service/hook 中通过 `api.order.list(params)` 调用。
+4. 禁止在业务代码中直接使用 `fetch`/`axios`，必须通过统一的 `api` 客户端。