@bams-app/work-cli 0.1.0 → 0.1.3

package/README.md

@@ -10,7 +10,7 @@ BAMS-Work 全局脚手架工具（类似 vue-cli 模式），提供**项目初
 
 | 能力          | 来源包                                                                                                                                 |
 | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| 项目/组件创建 | `@bams-app/create-ui-component`、`@bams-app/create-ui-page`、`@bams-app/create-ui-base`（内部引用 `@bams-app/ui-*-template`）          |
+| 项目/组件创建 | `@bams-app/create-ui-component`、`@bams-app/create-ui-page`、`@bams-app/create-ui-base`（模板内置于各包 `templates/`）                 |
 | 开发服务      | `@bams-app/ui-dev-server`（由模板写入用户项目 `devDependencies`，`npm run dev:ui <环境标识>` 本地启动；环境标识由第 1 个位置参数传入） |
 | 环境变量加载  | `@bams-app/shared-env`（同上；其 `lib/env-loader` 被 ui-dev-server 复用于解析环境标识）                                                |
 | 环境配置创建  | `@bams-app/create-env`（交互式生成 `.envs/.env.dev-<alias>`）                                                                          |
@@ -18,10 +18,10 @@ BAMS-Work 全局脚手架工具（类似 vue-cli 模式），提供**项目初
 | 批量页面创建  | `@bams-app/create-pages-from-components`（批量将 ui-_ 转为 page-_，复用 create-ui-page）                                               |
 | 公共配置      | `@bams-app/configs`（app-config.json、可配置组件插槽默认值，被 ui-dev-server 与 store 依赖）                                           |
 
-- `create` 生成 **scope 目录模式** Monorepo：根 `workspaces: ["demo-ui/*", "bams-components/*", "*-ui/*", "apex-web/*", "bams-ui"]`，
-  业务组件按 scope 目录存放（`energy-ui/ui-xxx`）。
-- `workspaces` 与仓库根 `package.json` 保持一致：`bams-components/*`、`apex-web/*` 等 glob 用于兼容
-  用户克隆进项目的既有组件包仓库（目录不存在时不影响安装，`create` 也不会默认创建它们）。
+- `create` 生成 **scope 目录模式**项目：业务组件按 scope 目录存放（`energy-ui/ui-xxx`）；
+  项目根 `package.json` 声明 `demo-ui/*`、`bams-components/*`、`*-ui/*`、`apex-web/*`、`bams-ui`
+  这些目录范围，用于兼容用户克隆进项目的既有组件包目录（目录不存在时不影响安装，
+  `create` 也不会默认创建它们）。
 - 项目根 `package.json` 的 `devDependencies` **只声明 `@bams-app/ui-dev-server` 一个**：
   能力包（`@bams-app/*`）与运行时依赖（vue、ant-design-vue、devextreme 等）的清单只在
   ui-dev-server 的 `dependencies` 维护**一处**，安装后提升到项目根 `node_modules`，
@@ -37,7 +37,7 @@ BAMS-Work 全局脚手架工具（类似 vue-cli 模式），提供**项目初
 flowchart LR
     subgraph WORK["work 仓库（全部可发布包）"]
         A["能力包<br/>packages/ · ui/ · configs/"]
-        B["开发工具与模板<br/>tooling/ · templates/"]
+        B["开发工具与模板<br/>tooling/"]
     end
     subgraph REG["私有 registry<br/>npm.hedpy.cn"]
         C["@bams-app/*"]
@@ -45,7 +45,7 @@ flowchart LR
     subgraph CLI["@bams-app/work-cli（全局 CLI）"]
         D["create / add / env<br/>pages-entry / pages-from-components"]
     end
-    subgraph PROJ["用户项目（Monorepo）"]
+    subgraph PROJ["用户项目"]
         E["package.json<br/>devDependencies：仅 ui-dev-server"]
         F["npm install<br/>依赖自动安装"]
         G["npm run dev:ui 环境标识<br/>本地 ui-dev-server"]
@@ -60,8 +60,8 @@ flowchart LR
 ```
 
 ```
-用户项目（Monorepo，scope 目录模式）
-├── package.json            # workspaces: demo-ui/*、bams-components/*、*-ui/*、apex-web/*、bams-ui
+用户项目（scope 目录模式）
+├── package.json            # 项目根配置
 ├── .bams-work/             # BAMS-Work 项目标记目录（勿删除）
 ├── .envs/.env.dev-<env>    # 环境变量
 ├── .proxy.js               # 自定义代理（可选）
@@ -80,8 +80,8 @@ npm i -g @bams-app/work-cli
 ## 使用
 
 ```bash
-# 初始化 Monorepo 项目模版
-bams-work create my-bams-project
+# 初始化项目模版
+work create my-bams-project
 cd my-bams-project
 npm install
 
@@ -90,17 +90,17 @@ npm run dev:ui demo                    # 加载 .envs/.env.dev-demo + 组件 ui-
 npm run dev:ui demo ui-order-list      # 指定组件（`-c ui-order-list` 等价）
 
 # 在 scope 目录下创建新组件
-bams-work add --dir energy-ui --name ui-order-list
-bams-work add --dir energy-ui --name page-order-list --type page
-bams-work add --dir demo-ui --name ui-base-btn --type base
+work add --dir energy-ui --name ui-order-list
+work add --dir energy-ui --name page-order-list --type page
+work add --dir demo-ui --name ui-base-btn --type base
 ```
 
 ### 命令一览
 
 | 命令                                               | 说明                                                                  |
 | -------------------------------------------------- | --------------------------------------------------------------------- |
-| `create <name>`                                    | 初始化 Monorepo 项目模版（含示例组件与 `.bams-work/` 标记）           |
-| `add --dir <scope> --name <name>`                  | 在 scope 目录下创建组件（component/page/base），并注册 workspace      |
+| `create <name>`                                    | 初始化项目模版（含示例组件与 `.bams-work/` 标记）                     |
+| `add --dir <scope> --name <name>`                  | 在 scope 目录下创建组件（component/page/base），并注册 scope 目录     |
 | `env`                                              | 交互式创建开发环境配置 `.envs/.env.dev-<alias>`（复用 create-env）    |
 | `pages-entry --dir <dir> --type <page\|component>` | 扫描 page-_/ui-_ 目录生成 webpack 动态入口（复用 create-pages-entry） |
 | `pages-from-components --dir <dir>`                | 批量将 ui-_ 组件转为 page-_ 页面（复用 create-pages-from-components） |
@@ -126,7 +126,7 @@ bams-work add --dir demo-ui --name ui-base-btn --type base
 
 所有 work 包统一发布到 npm registry，**默认官方 npm（registry.npmjs.org）**，通过环境变量
 `NPM_REGISTRY` 可随时切换到私有 registry（如 `https://npm.hedpy.cn/`）。work 下所有含
-`package.json` 的目录（`packages/`、`ui/`、`tooling/`、`templates/`、`cli/`、`configs/` 等）
+`package.json` 的目录（`packages/`、`ui/`、`tooling/`、`cli/`、`configs/` 等）
 都会被打包发布，`private` 包自动跳过：
 
 ```bash
@@ -155,60 +155,32 @@ cd work/configs && npm publish --registry=https://registry.npmjs.org/
 单包发布只影响该包，其他包版本号不变；需要整体提升版本时使用 `yarn publish-all`。
 发布官方 npm 时 `@bams-app` scope 会随首个 scoped 包自动创建，无需预先注册。
 
-`work-cli` 与 `create` 生成的项目均以 `"*"` 声明 `@bams-app/ui-dev-server`：仓库内经 yarn
-workspaces 链接到本地包，发布后自动解析为 registry 上最新的已发布版本，无需手动改版本号。
+`work-cli` 与 `create` 生成的项目均以 `"*"` 声明 `@bams-app/ui-dev-server`：仓库内直接链接到
+本地包，发布后自动解析为 registry 上最新的已发布版本，无需手动改版本号。
+用户项目升级时使用 `npm i @bams-app/ui-dev-server@latest`，该命令会把声明改写为 `^x.y.z`。
 
 ## 用户项目升级
 
-用户项目的 `devDependencies` 只声明 `@bams-app/ui-dev-server` 一个（`"*"`），能力包与
-运行时依赖全部作为它的传递依赖解析到同一份包，提升到项目根 `node_modules`。
+用户项目只声明 `@bams-app/ui-dev-server` 一个依赖，能力包与运行时依赖全部作为它的传递依赖解析到
+同一份包，提升到项目根 `node_modules`。
 
-### 为什么直接用 npm 命令带不动这些依赖
-
-能力包在 ui-dev-server 里声明为 `"*"`，运行时依赖是普通版本范围，而项目
-`package-lock.json` 已把它们逐个钉死在具体版本、且仍满足声明范围，npm 便不再重新解析：
-`npm install` 与 `npm update @bams-app/ui-dev-server` 都不会动它们；裸 `npm update` 虽能带上，
-但会重解析整棵依赖树、顺带升级其它第三方依赖。所以只能清掉它们在 lockfile 里的记录，
-让 npm 重新解析。
-
-### 升级步骤
+ui-dev-server 对能力包声明的是显式版本范围（`^x.y.z`），范围随 ui-dev-server 每次发布同步更新，
+因此升级就是一条命令：
 
 ```bash
-# 1. 按 ui-dev-server 的依赖清单清理 package-lock.json
-node -e "
-const fs = require('fs');
-const dev = JSON.parse(fs.readFileSync('node_modules/@bams-app/ui-dev-server/package.json', 'utf8'));
-const names = new Set([...Object.keys(dev.dependencies || {}), '@bams-app/ui-dev-server']);
-const lock = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'));
-let removed = 0;
-for (const section of ['packages', 'dependencies']) {
-    const container = lock[section];
-    if (!container) continue;
-    for (const key of Object.keys(container)) {
-        const name = key.replace(/^.*node_modules\//, '');
-        if (names.has(name)) { delete container[key]; removed++; }
-    }
-}
-fs.writeFileSync('package-lock.json', JSON.stringify(lock, null, 2) + '\n');
-console.log('已清理', removed, '条由 ui-dev-server 提供的依赖记录');
-"
-
-# 2. 这些包按 ui-dev-server 声明的版本重新解析，其余依赖保持锁定不动
-npm install
+npm i @bams-app/ui-dev-server@latest
 ```
 
-清理范围必须覆盖 ui-dev-server 声明的**全部**依赖：只删 `@bams-app/*` 的话，能力包会刷新，
-但 vue / axios 等运行时依赖仍停在 lockfile 里的旧版本。
+新版本的依赖范围与 `package-lock.json` 中钉住的旧版本不再匹配，npm 会自动重新解析整套能力包，
+无需手工清理 lockfile（历史版本遗留的 `*` 范围才需要旧办法，见 git 历史）。
 
-只想升 ui-dev-server 本身、不在意它带的依赖时，直接 `npm i @bams-app/ui-dev-server@latest`。
-跨大版本（0.1 → 0.2）先改 `package.json` 为 `"^0.2.0"`，再执行上面的两步。
+跨大版本（0.1 → 0.2）同理，直接执行上面的命令即可。
 
 ### 前提
 
-- 升级前确保对应版本已发布：`"*"` 只解析 registry 上已发布的版本。
+- 升级前确保对应版本已发布：能力包与 ui-dev-server 由 `yarn publish-all` 同批次发布。
 - registry 指向：`create` 不生成项目 `.npmrc`，`@bams-app/*` 默认走官方 npm
-  （registry.npmjs.org）；仅在内网隔离、必须走私服时，才在项目 `.npmrc` 手动加
-  `@bams-app:registry=https://npm.hedpy.cn/`（私服若存在同名旧版本，会遮蔽官方新版）。
+  （切私服需在执行 `create` 时指定 registry）。
 
 ## 环境要求
 

package/bin/work-cli.js

@@ -7,7 +7,7 @@ const { colorize } = require('../lib/utils');
 const pkg = require('../package.json');
 
 const COMMANDS = {
-    create: '初始化 Monorepo 项目模版',
+    create: '初始化项目模版',
     add: '在 scope 目录下创建组件（component/page/base）',
     env: '创建开发环境配置（.envs/.env.dev-<alias>）',
     'pages-entry': '扫描 page-*/ui-* 目录生成 webpack 动态入口',
@@ -24,7 +24,7 @@ function printUsage() {
     console.log(colorize('复用 work 已发布的包（create-env / create-ui-*）', 'gray'));
     console.log('');
     console.log(colorize('用法:', 'bold'));
-    console.log('  bams-work <command> [options]');
+    console.log('  work <command> [options]');
     console.log('');
     console.log(colorize('命令:', 'bold'));
     Object.entries(COMMANDS).forEach(([name, desc]) => {
@@ -32,11 +32,11 @@ function printUsage() {
     });
     console.log('');
     console.log(colorize('示例:', 'bold'));
-    console.log('  bams-work create my-bams-project        # 初始化 Monorepo 项目');
-    console.log('  bams-work add --dir energy-ui --name ui-order-list');
-    console.log('  bams-work env                               # 创建开发环境配置（交互式）');
-    console.log('  bams-work pages-entry --dir energy-ui --type page');
-    console.log('  bams-work pages-from-components --dir energy-ui');
+    console.log('  work create my-bams-project             # 初始化项目');
+    console.log('  work add --dir energy-ui --name ui-order-list');
+    console.log('  work env                               # 创建开发环境配置（交互式）');
+    console.log('  work pages-entry --dir energy-ui --type page');
+    console.log('  work pages-from-components --dir energy-ui');
     console.log('');
     console.log(colorize('开发调试:', 'bold'));
     console.log('  在项目根目录执行 npm run dev:ui <环境标识>（由项目本地 ui-dev-server 启动并加载 .envs/ 环境文件）');

package/commands/add.js

@@ -4,7 +4,7 @@ const { spawn } = require('child_process');
 const { findProjectRoot, toKebabCase, error, success, info } = require('../lib/utils');
 
 /**
- * 用法: bams-work add --dir <scope> --name <name> [--type component|page|base]
+ * 用法: work add --dir <scope> --name <name> [--type component|page|base]
  *       [--template <tpl>] [--use-component <name>] [--desc <text>]
  */
 function parseArgs(args) {
@@ -41,7 +41,7 @@ function ensureWorkspaceScope(projectRoot, scopeDir) {
         workspaces.push(pattern);
         pkg.workspaces = workspaces;
         fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
-        info(`已注册 workspace: ${pattern}`);
+        info(`已注册 scope 目录: ${pattern}`);
     }
 }
 
@@ -77,9 +77,9 @@ async function main(args) {
     const params = parseArgs(args);
 
     if (!params.name) {
-        error('用法: bams-work add --dir <scope> --name <name> [--type component|page|base]');
-        error('示例: bams-work add --dir energy-ui --name ui-order-list');
-        error('      bams-work add --dir energy-ui --name page-order-list --type page');
+        error('用法: work add --dir <scope> --name <name> [--type component|page|base]');
+        error('示例: work add --dir energy-ui --name ui-order-list');
+        error('      work add --dir energy-ui --name page-order-list --type page');
         process.exit(1);
     }
 
@@ -90,7 +90,7 @@ async function main(args) {
 
     const projectRoot = findProjectRoot(process.cwd());
     if (!projectRoot) {
-        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 work create <name>');
         process.exit(1);
     }
 
@@ -133,7 +133,7 @@ async function main(args) {
     success(`组件创建成功: ${toKebabCase(params.name)}（scope: ${scopeDir}）`);
     info(`开发: npm run dev:ui <环境标识> -c ${toKebabCase(params.name)}`);
     // UMD 命令暂时下线，恢复后取消注释
-    // info(`UMD: bams-work umd ${toKebabCase(params.name)}`);
+    // info(`UMD: work umd ${toKebabCase(params.name)}`);
 }
 
 module.exports = main;

package/commands/build.js

@@ -3,13 +3,13 @@ const path = require('path');
 const { findProjectRoot, error, info, run } = require('../lib/utils');
 
 /**
- * 用法: bams-work build [component] [-- <vue-cli args>]
+ * 用法: work build [component] [-- <vue-cli args>]
  * 委托 @bams-app/ui-dev-server/bin/build-app.js 构建宿主应用（production）
  */
 async function main(args) {
     const projectRoot = findProjectRoot(process.cwd());
     if (!projectRoot) {
-        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 work create <name>');
         process.exit(1);
     }
 

package/commands/create.js

@@ -43,7 +43,7 @@ async function main(args) {
     const projectNameArg = args.find((a) => !a.startsWith('-'));
 
     if (!projectNameArg) {
-        error('用法: bams-work create <project-name> [--force]');
+        error('用法: work create <project-name> [--force]');
         process.exit(1);
     }
 
@@ -116,9 +116,9 @@ async function main(args) {
     log('  npm run dev:ui demo ui-component-demo  # 指定组件（换环境改第 1 个参数）');
     log('');
     log('创建新组件：');
-    log('  bams-work add --dir energy-ui --name ui-order-list');
+    log('  work add --dir energy-ui --name ui-order-list');
     log('');
-    log('更多命令：bams-work --help');
+    log('更多命令：work --help');
     log('');
 }
 

package/commands/dev.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { findProjectRoot, error, info, run } = require('../lib/utils');
 
 /**
- * 用法: bams-work dev <env> [component] [--layout pc|touch] [-- <vue-cli args>]
+ * 用法: work dev <env> [component] [--layout pc|touch] [-- <vue-cli args>]
  * 委托 @bams-app/shared-env 加载环境变量，并启动 @bams-app/ui-dev-server 开发服务
  *
  * 已暂时下线（入口 COMMANDS 与 DISABLED_COMMANDS 见 bin/work-cli.js）：
@@ -13,7 +13,7 @@ const { findProjectRoot, error, info, run } = require('../lib/utils');
 async function main(args) {
     const projectRoot = findProjectRoot(process.cwd());
     if (!projectRoot) {
-        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 work create <name>');
         process.exit(1);
     }
 
@@ -49,8 +49,8 @@ async function main(args) {
     }
 
     if (!envAlias) {
-        error('用法: bams-work dev <env> [component] [--layout pc|touch]');
-        error('示例: bams-work dev demo ui-component-demo');
+        error('用法: work dev <env> [component] [--layout pc|touch]');
+        error('示例: work dev demo ui-component-demo');
         process.exit(1);
     }
 

package/commands/umd.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { findProjectRoot, toCamelCase, exists, isDirectory, readJson, error, info, run } = require('../lib/utils');
 
 /**
- * 用法: bams-work umd [component] [--out <dir>] [--name <name>] [--entry <file>]
+ * 用法: work umd [component] [--out <dir>] [--name <name>] [--entry <file>]
  * component 缺省时自动收集 workspaces 下所有组件
  * 委托 @bams-app/ui-dev-server/bin/build-umd.js 构建组件 UMD 产物
  */
@@ -110,7 +110,7 @@ function generateEntryFile({ projectRoot, components }) {
 async function main(args) {
     const projectRoot = findProjectRoot(process.cwd());
     if (!projectRoot) {
-        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 work create <name>');
         process.exit(1);
     }
 
@@ -125,7 +125,7 @@ async function main(args) {
     }
 
     if (components.length === 0) {
-        error('未找到任何组件（workspaces 下需存在 ui-* / page-* 目录），请先执行 bams-work add --dir <scope> --name ui-xxx');
+        error('未找到任何组件（scope 目录下需存在 ui-* / page-* 目录），请先执行 work add --dir <scope> --name ui-xxx');
         process.exit(1);
     }
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bams-app/work-cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "BAMS-Work 全局开发工具：复用 work 已发布的包（create-env / create-ui-*）提供项目初始化、组件创建与环境配置能力，开发调试由用户项目本地的 ui-dev-server 承担",
   "main": "index.js",
   "bin": {
-    "bams-work": "./bin/work-cli.js"
+    "work": "./bin/work-cli.js"
   },
   "files": [
     "bin",
@@ -13,12 +13,12 @@
     "templates"
   ],
   "dependencies": {
-    "@bams-app/create-env": "*",
-    "@bams-app/create-pages-entry": "*",
-    "@bams-app/create-pages-from-components": "*",
-    "@bams-app/create-ui-base": "*",
-    "@bams-app/create-ui-component": "*",
-    "@bams-app/create-ui-page": "*"
+    "@bams-app/create-env": "^0.1.3",
+    "@bams-app/create-pages-entry": "^0.1.3",
+    "@bams-app/create-pages-from-components": "^0.1.3",
+    "@bams-app/create-ui-base": "^0.1.3",
+    "@bams-app/create-ui-component": "^0.1.3",
+    "@bams-app/create-ui-page": "^0.1.3"
   },
   "engines": {
     "node": ">=16.7.0"

package/templates/project/README.md

@@ -1,182 +1,69 @@
-# BAMS-Work Monorepo 项目
+# BAMS-Work 组件开发项目
 
-基于 `@bams-app/work-cli` 初始化的组件包开发项目
+由 `@bams-app/work-cli` 初始化，组件按 scope 目录组织。
 
-## 目录结构
+## 目录
 
 ```
-.
-├── package.json          # Monorepo 根（见 package.json 的 workspaces）
-├── .bams-work/           # BAMS-Work 项目标记目录，勿删除
-├── .envs/                # 环境配置（.env.dev-<env>）
-├── .proxy.js             # 自定义开发代理（可选）
-├── demo-ui/              # 默认组件 scope
-│   └── ui-component-demo # 示例组件
-└── <scope>-ui/           # 其他业务 scope 目录（如 energy-ui/，add 时创建）
-    └── ui-xxx
+package.json                # 项目根配置
+.bams-work/                 # 项目标记目录，勿删
+.envs/                      # 环境配置 .env.dev-<env>
+.proxy.js                   # 自定义代理（可选）
+demo-ui/ui-component-demo   # 示例组件
+<scope>-ui/ui-xxx           # 业务组件（add 时创建）
 ```
 
-## 快速开始
+## 前置条件（必需）
 
-```bash
-npm install            # 安装依赖到根 node_modules（含项目本地的 ui-dev-server）
-npm run dev:ui demo    # 启动开发环境（环境标识 demo → .envs/.env.dev-demo，示例端口 8700）
-```
-
-> 开发调试由**项目本地**的 `@bams-app/ui-dev-server` 启动（`npm run dev:ui <环境标识>`），
-> 环境标识作为位置参数传入（`demo` → `.envs/.env.dev-demo`）。
-> 其余 `bams-work` 命令都在**项目根目录**（含 `.bams-work/` 的目录）执行。
-> 全局帮助 `bams-work --help`，版本 `bams-work --version`。
-
-## 命令一览
-
-| 命令                                                 | 作用                        |
-| ---------------------------------------------------- | --------------------------- |
-| `npm run dev:ui <环境标识>`                          | 启动开发服务（最常用）      |
-| `add --dir <scope> --name <name>`                    | 新建组件 / 页面 / 基础组件  |
-| `env`                                                | 交互式创建开发环境配置      |
-| `pages-entry --dir <scope> --type <page\|component>` | 生成 webpack 动态入口       |
-| `pages-from-components --dir <scope>`                | 批量将 `ui-*` 转为 `page-*` |
-
-### 1. `npm run dev:ui <环境标识>` — 启动开发环境
-
-`dev:ui` 即项目本地的 `ui-dev-server`，**环境标识用位置参数指定（不加 `--` 分隔符）**，
-追加的位置参数会覆盖默认值：
+必须先全局安装 CLI，否则 `work` 命令（`work add` / `work env` / `work pages-entry`）不可用：
 
 ```bash
-npm run dev:ui demo                                # 加载 .envs/.env.dev-demo + 默认组件 ui-component-demo
-npm run dev:ui demo ui-order-list                  # 指定要调试的组件
-npm run dev:ui test                                # 换环境：加载 .envs/.env.dev-test
-npm run dev:ui demo ui-order-list -l touch         # 切换布局（默认 pc）
-npm run dev:ui demo ui-order-list -- --port 8080   # `--` 之后的参数透传给 vue-cli-service
+npm i -g @bams-app/work-cli
 ```
 
-| 参数                | 必填 | 说明                                                               |
-| ------------------- | ---- | ------------------------------------------------------------------ |
-| 位置参数 1          | 是   | 环境标识（如 `demo` → `.envs/.env.dev-demo`），也可传 env 文件路径 |
-| 位置参数 2          | 否   | 组件目录名（如 `ui-order-list`），省略时默认 `ui-component-demo`   |
-| `--env`、`-e`       | 否   | 等价于位置参数 1（显式指定环境标识或 env 文件路径）                |
-| `--component`、`-c` | 否   | 等价于位置参数 2                                                   |
-| `--layout`、`-l`    | 否   | 布局：`pc`（默认）/ `touch`                                        |
-| `--` 之后的参数     | 否   | 原样透传给底层 `vue-cli-service`（如 `--port`、`--open`）          |
-
-环境文件不存在时直接报错并给出路径，不会静默使用默认值。
-
-启动地址与接口代理取自环境文件：`PORT` 决定本地端口，`PROXY_TARGET` 决定后端代理目标。
-
-### 2. `bams-work add` — 新建组件
+## 开始
 
 ```bash
-bams-work add --dir energy-ui --name ui-order-list                # 业务组件（默认 type=component）
-bams-work add --dir energy-ui --name page-order-list --type page  # 页面
-bams-work add --dir demo-ui --name ui-base-btn --type base        # 基础组件
+npm install
+npm run dev:ui demo            # 环境 demo → .envs/.env.dev-demo
 ```
 
-| 参数     | 必填 | 说明                                                                                                                    |
-| -------- | ---- | ----------------------------------------------------------------------------------------------------------------------- |
-| `--dir`  | 是   | scope 目录名（小写字母、数字、连字符，如 `energy-ui`）；不存在会自动创建，并自动注册到根 `package.json` 的 `workspaces` |
-| `--name` | 是   | 组件名，自动转为 kebab-case；`component`/`base` 建议 `ui-` 前缀，`page` 建议 `page-` 前缀                               |
-| `--type` | 否   | `component`（默认）/ `page` / `base`                                                                                    |
-| `--desc` | 否   | 组件描述                                                                                                                |
-
-创建完成后会提示用哪条 `npm run dev:ui` 命令调试。
-
-### 3. `bams-work env` — 创建开发环境
-
-交互式向导，无需记参数，生成 `.envs/.env.dev-<标识>`：
+`dev:ui` 由项目本地的 `@bams-app/ui-dev-server` 提供：
 
 ```bash
-bams-work env
+npm run dev:ui demo ui-order-list           # 位置参数1=环境标识，位置参数2=组件目录名
+npm run dev:ui demo ui-order-list -l touch  # 布局 pc（默认）/ touch
+npm run dev:ui demo -- --port 8080          # `--` 之后透传给 vue-cli-service
 ```
 
-流程：列出已有环境与已占用端口 → 选择创建方式 → 输入环境标识 → 逐项填写配置 → 预览确认后写入。
-
-创建方式二选一：
+环境文件缺失会直接报错；`PORT` 决定端口，`PROXY_TARGET` 决定代理目标。
 
-- **快速复制**：基于现有环境文件，或 `production` 空值模板，只改差异项（推荐）
-- **自定义配置**：从默认模板逐项填写
+## 命令
 
-环境标识即 `npm run dev:ui` 的第 1 个位置参数：`bams-work env` 创建了 `test`，就用 `npm run dev:ui test` 启动。
+| 命令                                                                               | 作用                                                                        |
+| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `npm run dev:ui <环境标识> [组件名]`                                               | 启动开发服务                                                                |
+| `work add --dir <scope> --name <name> [--type component\|page\|base] [--desc ...]` | 新建组件/页面/基础组件；scope 目录不存在会自动创建并注册到根 `package.json` |
+| `work env`                                                                         | 交互式生成 `.envs/.env.dev-<标识>`                                          |
+| `work pages-entry --dir <scope> --type page\|component`                            | 生成构建用动态入口（内部使用）                                              |
+| `work pages-from-components --dir <scope>`                                         | 把 `ui-*` 批量复制为 `page-*`                                               |
 
-常用字段（可直接编辑对应环境文件，`dev` 每次启动都会重新加载）：
+环境文件字段：`PORT`、`PROXY_TARGET`、`BASE_URL`、`VUE_APP_*` 等，见模板文件；改完重跑 `dev:ui` 生效。
 
-| 字段                                                                                        | 说明                                                 |
-| ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| `NODE_ENV`                                                                                  | 运行环境，固定 `development`                         |
-| `PORT`                                                                                      | 开发服务器端口（创建时自动避开其他环境已占用的端口） |
-| `PROXY_TARGET`                                                                              | 接口代理目标（后端服务地址）                         |
-| `BASE_URL`                                                                                  | 应用基础路径，默认 `/`                               |
-| `COMPONENT_LOGIN`、`COMPONENT_STARTR_LAYOUT`                                                | 可配置组件插槽：登录页 / 布局组件包名                |
-| `VUE_APP_TITLE`、`VUE_APP_SYS_NAME`、`VUE_APP_SYS_CODE`                                     | 浏览器标签标题、系统名称、系统编码                   |
-| `VUE_APP_SHOW_HEADER`、`VUE_APP_ENABLE_THEME`、`VUE_APP_THEME_MODE`、`VUE_APP_THEME_PRESET` | 头部显示与主题（模式 / 预设色）                      |
-| `VUE_APP_ENABLE_I18N`、`VUE_APP_ENABLE_VERSION_LOG`、`VUE_APP_TABS_EXPAND_STATE`            | 国际化、版本日志、Tabs 展开/收起                     |
-| `VUE_APP_ENABLE_CAPTCHA`、`VUE_APP_ENABLE_MESSAGE_VOICE`、`VUE_APP_MESSAGE_WS_URL`          | 登录验证码、消息告警通知及其 WS 地址                 |
-| `VUE_APP_LOGIN_URL`、`VUE_APP_LOGIN_PUBLIC_KEY`、`VUE_APP_WEBSOCKET_URL`                    | 登录页地址、登录公钥、WebSocket 地址                 |
-| `VUE_APP_DEVEXTREME_LICENSE_KEY`                                                            | DevExtreme 许可证密钥（可留空）                      |
+## 依赖升级
 
-### 4. 升级 ui-dev-server 提供的依赖
-
-能力包与运行时依赖（vue、ant-design-vue、devextreme 等）由 ui-dev-server 提供，不在项目
-`package.json` 中声明；lockfile 已把它们逐个钉死，所以 `npm install`、
-`npm i @bams-app/ui-dev-server@latest`、`npm update @bams-app/ui-dev-server` 都**不会**刷新
-它们（只换掉 ui-dev-server 自己），裸 `npm update` 又会重解析整棵依赖树。
-
-清掉 lockfile 中这些包的记录，再让 npm 按 ui-dev-server 的声明重新解析：
+项目只声明 `@bams-app/ui-dev-server`，能力包与 vue、devextreme 等运行时依赖都由它提供并提升到根 `node_modules`。
+ui-dev-server 对能力包声明的是显式版本范围（`^x.y.z`），范围随它每次发布同步更新，因此升级就是一条命令：
 
 ```bash
-# 1. 按 ui-dev-server 的依赖清单清理 package-lock.json
-node -e "
-const fs = require('fs');
-const dev = JSON.parse(fs.readFileSync('node_modules/@bams-app/ui-dev-server/package.json', 'utf8'));
-const names = new Set([...Object.keys(dev.dependencies || {}), '@bams-app/ui-dev-server']);
-const lock = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'));
-let removed = 0;
-for (const section of ['packages', 'dependencies']) {
-    const container = lock[section];
-    if (!container) continue;
-    for (const key of Object.keys(container)) {
-        const name = key.replace(/^.*node_modules\//, '');
-        if (names.has(name)) { delete container[key]; removed++; }
-    }
-}
-fs.writeFileSync('package-lock.json', JSON.stringify(lock, null, 2) + '\n');
-console.log('已清理', removed, '条由 ui-dev-server 提供的依赖记录');
-"
-
-# 2. 这些包按 ui-dev-server 声明的版本重新解析，其余依赖保持锁定不动
-npm install
+npm i @bams-app/ui-dev-server@latest
 ```
 
-只想升 ui-dev-server 本身、不在意它带的依赖时，直接 `npm i @bams-app/ui-dev-server@latest`。
-
-### 5. 其他命令
-
-- `bams-work pages-entry --dir <scope> --type page|component`：扫描该 scope 下的 `page-*` / `ui-*` 目录，生成 webpack 动态入口 `build-components-entry.js`（构建流程内部使用，一般无需手动执行）
-- `bams-work pages-from-components --dir <scope>`：把该 scope 下的 `ui-*` 组件批量复制为 `page-*` 页面
-
-## 首次安装
-
-```bash
-npm install
-```
-
-项目只声明 `@bams-app/ui-dev-server` 一个开发依赖，能力包（`@bams-app/components` 等）与
-运行时依赖（vue、ant-design-vue、devextreme、pinia、axios、dayjs 等）都由它提供，
-安装后提升到项目根 `node_modules`，业务组件与开发环境共用同一份实例。升级这些依赖只需
-更新 ui-dev-server（见上文），无需逐个改版本号。
-
-## 升级 CLI
-
-```bash
-npm i -g @bams-app/work-cli@latest
-```
+新范围与 `package-lock.json` 中钉住的旧版本不再匹配，npm 会自动重新解析整套能力包，无需手工清理 lockfile。
 
-全局 CLI 只负责创建项目、组件与环境配置，开发调试由项目本地的 `npm run dev:ui` 承担；
-项目依赖按上文「升级 ui-dev-server 提供的依赖」清理 lockfile 后升级。
+全局 CLI 升级：`npm i -g @bams-app/work-cli@latest`。
 
-## 自定义配置
+## 自定义
 
-- 代理：创建项目根 `.proxy.js`（见 `.proxy.js.example`）。其中声明的前缀优先于内置默认前缀
-  （`/bams-assets`、`/bams-ui-umd`、`/bams-app`、`/admin-api`、`/preview`，target 取环境文件中的
-  `PROXY_TARGET`），内置默认仅补充未声明项；键序即匹配序，修改后需重启 `npm run dev:ui`
-- webpack 扩展：创建项目根 `vue.config.extend.js`（导出对象或 `({ env, projectRoot }) => 对象`）
+- 代理：项目根 `.proxy.js`（参考 `.proxy.js.example`），声明的前缀优先于内置默认，修改后需重启
+- webpack：项目根 `vue.config.extend.js`，导出对象或 `({ env, projectRoot }) => 对象`

package/templates/project/package.json

@@ -2,7 +2,7 @@
   "name": "bams-work-project",
   "version": "0.0.6",
   "private": true,
-  "description": "BAMS-Work Monorepo 项目",
+  "description": "BAMS-Work 项目",
   "workspaces": [
     "demo-ui/*",
     "bams-components/*",
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "dev:ui": "ui-dev-server",
-    "add": "bams-work add"
+    "add": "work add"
   },
   "devDependencies": {
     "@bams-app/ui-dev-server": "*"