listpage_cli 0.0.312 → 0.0.313

package/bin/adapters/cli-interaction.js

@@ -156,9 +156,12 @@ function printHelp() {
         `    用法: ${helpColor("listpage_cli init", "dim")}`,
         "    说明: 进入中文引导式交互，按提示填写即可",
         "",
-        `  ${helpColor("install-skill", "green")}`,
-        `    用法: ${helpColor("listpage_cli install-skill [skillName] [--project]", "dim")}`,
-        "    说明: 安装技能到 Cursor；默认 skillName 为 test，安装到当前命令执行目录的 .cursor/skills/",
+        `  ${helpColor("skill", "green")}`,
+        `    用法: ${helpColor("listpage_cli skill list", "dim")}`,
+        "    说明: 列出 CLI 包内可安装的技能名称（模板目录下的子文件夹）",
+        "",
+        `    用法: ${helpColor("listpage_cli skill add [技能名称]", "dim")}`,
+        "    说明: 安装技能到 Cursor；省略技能名时默认为 test，安装到当前命令执行目录的 .cursor/skills/",
         "",
         `  ${helpColor("project", "green")}`,
         `    用法: ${helpColor("listpage_cli project build", "dim")}`,

package/bin/adapters/node-fs-adapter.js

@@ -88,6 +88,14 @@ function createNodeFsAdapter() {
                 throw toFsPortError("writeBuffer", targetPath, error);
             }
         },
+        removeDirRecursive: (targetPath) => {
+            try {
+                (0, fs_1.rmSync)(targetPath, { recursive: true, force: true });
+            }
+            catch (error) {
+                throw toFsPortError("removeDirRecursive", targetPath, error);
+            }
+        },
     };
 }
 function toFsPortError(operation, targetPath, error) {

package/bin/app/parse-args.js

@@ -7,7 +7,7 @@ exports.parseCommandOptions = parseCommandOptions;
 exports.parseCommandPositionals = parseCommandPositionals;
 const KNOWN_COMMANDS = new Set([
     "init",
-    "install-skill",
+    "skill",
     "project",
     "lark",
 ]);

package/bin/cli.js

@@ -5,7 +5,7 @@ const cli_interaction_1 = require("./adapters/cli-interaction");
 const execute_1 = require("./app/execute");
 const command_result_1 = require("./domain/command-result");
 const init_command_1 = require("./commands/init-command");
-const install_skill_command_1 = require("./commands/install-skill-command");
+const skill_command_1 = require("./commands/skill-command");
 const project_command_1 = require("./commands/project-command");
 const lark_command_1 = require("./commands/lark-command");
 const node_fs_adapter_1 = require("./adapters/node-fs-adapter");
@@ -23,7 +23,7 @@ const initCommandHandler = (0, init_command_1.createInitCommandHandler)({
     fs: fsAdapter,
     files: filesystemCapability,
 });
-const installSkillCommandHandler = (0, install_skill_command_1.createInstallSkillCommandHandler)({
+const skillCommandHandler = (0, skill_command_1.createSkillCommandHandler)({
     fs: fsAdapter,
     files: filesystemCapability,
     config: {
@@ -45,7 +45,7 @@ async function main() {
         printVersion: cli_interaction_1.printVersion,
         handlers: {
             init: initCommandHandler,
-            "install-skill": installSkillCommandHandler,
+            skill: skillCommandHandler,
             project: projectCommandHandler,
             lark: larkCommandHandler,
         },

package/bin/commands/skill/add-command.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillAddCommandHandler = createSkillAddCommandHandler;
+const skill_add_service_1 = require("../../services/skill-add-service");
+function createSkillAddCommandHandler(deps) {
+    return async (input) => {
+        return (0, skill_add_service_1.runSkillAddFlow)(input, deps);
+    };
+}

package/bin/commands/skill/list-command.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillListCommandHandler = createSkillListCommandHandler;
+const skill_list_service_1 = require("../../services/skill-list-service");
+function createSkillListCommandHandler(deps) {
+    return async (_input) => {
+        return (0, skill_list_service_1.runSkillListFlow)(deps);
+    };
+}

package/bin/commands/skill-command.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillCommandHandler = createSkillCommandHandler;
+const command_result_1 = require("../domain/command-result");
+const add_command_1 = require("./skill/add-command");
+const list_command_1 = require("./skill/list-command");
+function createSkillCommandHandler(deps) {
+    const add = (0, add_command_1.createSkillAddCommandHandler)(deps);
+    const list = (0, list_command_1.createSkillListCommandHandler)(deps);
+    return async (input) => {
+        const sub = input.positionals[0];
+        switch (sub) {
+            case "add":
+                return add(input);
+            case "list":
+                return list(input);
+            default:
+                return (0, command_result_1.commandError)("用法: listpage_cli skill add [技能名称]\n       listpage_cli skill list", command_result_1.COMMAND_ERROR_CODES.unknownCommand, 1);
+        }
+    };
+}

package/bin/services/{install-skill-service.js → skill-add-service.js}

@@ -1,18 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runInstallSkillFlow = runInstallSkillFlow;
+exports.runSkillAddFlow = runSkillAddFlow;
 const command_result_1 = require("../domain/command-result");
-function runInstallSkillFlow(input, deps) {
-    const skillName = input.positionals[0] || deps.config.defaultSkillName;
+function runSkillAddFlow(input, deps) {
+    const skillName = input.positionals[1] ?? deps.config.defaultSkillName;
     const sourceDir = deps.fs.join(deps.config.getSkillTemplateRoot(), skillName);
     if (!deps.fs.exists(sourceDir)) {
         return (0, command_result_1.commandError)(`技能 ${skillName} 不存在: ${sourceDir}`, command_result_1.COMMAND_ERROR_CODES.skillNotFound, 1);
     }
-    const targetDirResult = resolveTargetDir(input, skillName, deps.fs);
+    const targetDirResult = resolveTargetDir(skillName, deps.fs);
     if (targetDirResult.kind === "error") {
         return targetDirResult.result;
     }
     try {
+        if (deps.fs.exists(targetDirResult.targetDir)) {
+            deps.fs.removeDirRecursive(targetDirResult.targetDir);
+        }
         deps.files.copySkillDir(sourceDir, targetDirResult.targetDir);
         return (0, command_result_1.commandOk)(`已安装 ${skillName} 技能到 ${targetDirResult.targetDir}`);
     }
@@ -21,7 +24,7 @@ function runInstallSkillFlow(input, deps) {
         return (0, command_result_1.commandError)(`安装技能失败(${skillName} -> ${targetDirResult.targetDir}): ${message}`, command_result_1.COMMAND_ERROR_CODES.fsOperationFailed, 1);
     }
 }
-function resolveTargetDir(input, skillName, fs) {
+function resolveTargetDir(skillName, fs) {
     const baseDir = fs.cwd();
     if (!baseDir || !baseDir.trim()) {
         return {

package/bin/services/skill-list-service.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkillListFlow = runSkillListFlow;
+const command_result_1 = require("../domain/command-result");
+function runSkillListFlow(deps) {
+    const root = deps.config.getSkillTemplateRoot();
+    if (!deps.fs.exists(root)) {
+        return (0, command_result_1.commandError)(`技能模板目录不存在: ${root}`, command_result_1.COMMAND_ERROR_CODES.invalidPath, 1);
+    }
+    try {
+        const names = deps.fs
+            .readDir(root)
+            .filter((name) => {
+            const entry = deps.fs.join(root, name);
+            return deps.fs.exists(entry) && deps.fs.isDirectory(entry);
+        })
+            .sort((a, b) => a.localeCompare(b));
+        if (names.length === 0) {
+            return (0, command_result_1.commandOk)("(暂无可用技能)");
+        }
+        return (0, command_result_1.commandOk)(names.join("\n"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return (0, command_result_1.commandError)(`列出技能失败: ${message}`, command_result_1.COMMAND_ERROR_CODES.fsOperationFailed, 1);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listpage_cli",
-  "version": "0.0.312",
+  "version": "0.0.313",
   "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.312"
+    "listpage-next-nest": "~0.0.313"
   },
   "devDependencies": {
     "@nestjs/schematics": "^11.0.0",

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

@@ -10,8 +10,8 @@
     "preview": "rsbuild preview"
   },
   "dependencies": {
-    "listpage-http": "0.0.312",
-    "listpage-components": "0.0.312",
+    "listpage-http": "0.0.313",
+    "listpage-components": "0.0.313",
     "antd": "6.3.1",
     "ahooks": "^3.9.5",
     "@ant-design/icons": "~6.0.2",

package/templates/skills-template/listpage-cli-deploy/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: listpage-cli-deploy
+description: Runs listpage_cli project build, release, and deploy in sequence (Docker build/push to registry and remote container). After a successful deploy, derive and tell the user the app access URL from listpage.config.json and backend listen port (see skill body). Use ONLY when the user explicitly asks to deploy using listpage_cli—e.g. mentions deploying with listpage_cli, listpage_cli 部署, or similar. Do NOT use for generic deployment, Docker/compose/K8s/CI, or Aliyun push without an explicit listpage_cli request. Default tag/environment is dev; users may name other environments in listpage.config.json docker.releaseProfiles (e.g. test, prod).
+---
+
+# listpage_cli 自动化部署
+
+## 何时使用本技能
+
+- **仅当用户明确说要通过 `listpage_cli` 部署**（例如：用 listpage_cli 部署、listpage_cli 发版等**且语境指向该 CLI**）时再应用本技能。
+- **不要**因泛泛的「部署」「上线」「打镜像」「推阿里云」等就启用；除非用户同时点明 **listpage_cli**。
+
+## Tag 与环境
+
+- `project release` / `project deploy` 的 **`<tag>`** 在习惯上对应**环境名**（开发 / 测试 / 生产等），与 `listpage.config.json` 里 **`docker.releaseProfiles`** 下的 key 一致；同一仓库可配置多套 profile（如 `dev`、`test`、`prod`），每套可有各自的 `tag`、`envFile` 等。
+- **若用户未指定环境或 tag，默认使用 `dev`**。
+
+在**项目根目录**（需存在 `listpage.config.json`）按顺序执行三条命令即可完成构建、镜像推送与远程容器部署。
+
+## 前置条件
+
+- 已安装并可执行 `listpage_cli`（可先运行 `listpage_cli --help` 核对子命令）。
+- 本机已安装 **Docker**，且 **Docker 守护进程已启动**（`release` / `deploy` 会用到本地 Docker 与远程配置）。
+- `listpage.config.json` 中 `docker.registry`、`docker.remote`、`docker.releaseProfiles` 等已按目标环境填好（见下文「常见坑」）。
+
+## 部署步骤（顺序固定）
+
+在项目根目录执行：
+
+```bash
+listpage_cli project build
+```
+
+- 校验当前目录为有效项目根，构建产物写入 **`.listpage/output`**。
+
+```bash
+listpage_cli project release <tag>
+```
+
+- 默认：`listpage_cli project release dev`（未指定环境时）。
+- `<tag>` 与 `listpage.config.json` 中 `docker.releaseProfiles` 的环境 key 对齐（如 `dev` / `test` / `prod`）；也可用 CLI 覆盖项，见 `listpage_cli --help` 中 `project release` 说明。
+- 流程：校验 `.listpage/output` → 登录 / 构建 / 打 tag / 推送到配置的镜像仓库。
+
+```bash
+listpage_cli project deploy <tag>
+```
+
+- 默认：`listpage_cli project deploy dev`（与 `release` 使用同一环境名）。
+- 使用 `docker.remote` + `docker.container` 部署；支持 `ports`、`envFile`、`env` 等合并。
+- 若镜像已在目标环境且仅需更新容器步骤，可使用 CLI 中的 `--skip-image`（以 `listpage_cli --help` 为准）。
+
+**CLI 参数优先级**（来自官方说明）：`CLI 参数 > profile > 配置文件中的 base 项`。可选参数包括 `--profile`、`--platform`、`--env KEY=VALUE` 等，需要时查阅 `listpage_cli --help`。
+
+## 部署成功后：告知用户访问地址
+
+在 **`project deploy` 成功结束**后，必须结合**项目根目录的 `listpage.config.json`**（以及必要时后端监听端口）拼出**应用访问地址**，并用一句话告诉用户。**不要**把 `docker.registry` 密码、`envFile` 内容等敏感信息写入回复。
+
+### 推导规则（按顺序）
+
+1. **主机（host）**  
+   使用 `docker.remote.host`（远程部署目标机的 IP 或域名）。**不要**用 `docker.remote.port`（那是连接 Docker API 的端口，例如 2376，不是浏览器访问端口）。
+
+2. **协议（scheme）**  
+   - **默认**：面向用户的应用 URL 使用 **`http`**。  
+   - `docker.remote.protocol`（如 `https`）仅表示连接 **Docker daemon** 的方式，**不能**直接当作浏览器访问应用的协议。  
+   - 若用户在前方挂了 **Nginx / 负载均衡 / 全站 HTTPS**，实际对外可能是 **`https`**；技能无法从配置文件唯一确定时，以 **`http` + host + 端口** 为主，并**简短说明**「若前面有 HTTPS 终止，请改用 https」。
+
+3. **路径（pathname / 前缀）**  
+   - **一般情况**：路径前缀与 **`docker.container.name`** 一致，格式为 **`/<container.name>`**（注意前导 `/`，且通常**全小写**与配置一致）。  
+   - **少数差异**：若前端 `assetPrefix` / `base`（如 `apps/fe` 的 `rsbuild.config.ts`）与 `docker.container.name` 不一致，应以**前端实际配置的 public 路径**为准（部署仍成功但路径不同时需核对前端）。默认在技能中优先 **`docker.container.name`**。
+
+4. **端口（浏览器访问的 host 端口）**  
+   读取 `docker.container.ports` 中每一项 **`"hostPort:containerPort"`** 字符串（与 Docker `-p` 一致）。  
+   - 先确定**容器内后端 HTTP 监听端口**：查看 `servers/be`（或配置里 `artifacts.backend.projectDir`）中 `listen(...)`、`Dockerfile` 的 `EXPOSE` 或 `PORT` 环境变量；常见为 **3000**。  
+   - 在 `ports` 数组里找到 **右侧（container）端口等于该后端端口** 的那一条，取**左侧（host）端口**作为 URL 中的端口。  
+   - **多条映射时**：始终使用「**对应后端对外提供 Web 服务的那一个容器端口**」所映射到主机上的端口，而不是 Docker API 或其它服务端口。  
+   - **单条映射**（如 `"3333:3000"`）：后端在容器内监听 3000 → 浏览器访问 **`3333`**。
+
+5. **拼 URL**  
+
+   `{scheme}://{docker.remote.host}:{上一步得到的 host 端口}/{路径前缀去掉多余斜杠}`  
+
+   路径前缀：若规则 3 得到 `/<name>`，则完整示例形态为：  
+   `http://{host}:{hostPort}/{container.name}/`  
+   末尾是否带 `/` 可按习惯，保持与前端 `assetPrefix` 一致即可。
+
+### 示例（与配置字段对应）
+
+若 `docker.remote.host` 为 `localhost`，`docker.container.name` 为 `contract-payment-collection`，`docker.container.ports` 为 `["3333:3000"]`，且后端在容器内监听 **3000**，则访问地址为：
+
+`http://localhost:3333/contract-payment-collection`
+
+（若用户仅配置了 http 场景，上述即为默认输出；支持 https 时由用户或前置代理决定，可在说明中一句带过。）
+
+## 常见坑与配置要点
+
+### 1. Dockerfile 基础镜像（如 `FROM node:25-slim`）
+
+本地构建镜像时，若基础镜像未拉取过，`docker build` 可能失败或变慢。部署前可在本机先执行 `docker pull node:25-slim`（或与 `servers/be/Dockerfile` 中 `FROM` 一致的镜像），保证与构建环境一致。
+
+### 2. `docker.remote.tls`（ca / cert / key）
+
+`listpage.config.json` 里 `docker.remote.tls` 的 `ca`、`cert`、`key` 路径指向的证书**与目标远程 Docker 主机绑定**；换一台部署机或重建 TLS 时，需替换为对应文件并保持路径可访问。
+
+### 3. `docker.build.platform`（如 `linux/amd64`）
+
+该字段影响**构建出的镜像架构**。例如：在 Apple Silicon Mac 上若要把镜像跑到 **x86 云服务器**，通常使用 `linux/amd64`；若目标为本机或 ARM 机器，需改为匹配的 `platform`（或通过 CLI 传 `--platform` 覆盖）。与运行环境不一致会导致容器无法运行或性能异常。
+
+### 4. 阿里云镜像仓库账号
+
+`docker.registry` 中的 `url`、`namespace`、`username`、`password` 为**敏感信息**。技能与文档中只描述「在配置中填写」，不要在对话、提交记录或示例中粘贴真实密码；
+
+## 快速排错
+
+| 现象 | 可检查项 |
+|------|----------|
+| `build` 失败 | 是否在项目根目录、`listpage.config.json` 是否完整、前后端构建脚本是否正常 |
+| `release` 失败 | Docker 是否启动、基础镜像是否可拉取、registry 账号与网络、platform 是否与预期一致 |
+| `deploy` 失败 | `docker.remote` 地址/端口/协议、TLS 证书是否匹配当前主机、`envFile` 路径是否存在 |
+
+## 参考命令说明
+
+执行 `listpage_cli --help` 可查看 `project build` / `project release` / `project deploy` 的完整参数与备注。

package/bin/commands/install-skill-command.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createInstallSkillCommandHandler = createInstallSkillCommandHandler;
-const install_skill_service_1 = require("../services/install-skill-service");
-function createInstallSkillCommandHandler(deps) {
-    return async (input) => {
-        return (0, install_skill_service_1.runInstallSkillFlow)(input, deps);
-    };
-}