@bams-app/work-cli 0.0.9 → 0.1.0

package/README.md

@@ -1,35 +1,35 @@
 # @bams-app/work-cli
 
-BAMS-Work 全局开发工具（类似 vue-cli 模式），提供**项目初始化**与**组件开发命令**。
+BAMS-Work 全局脚手架工具（类似 vue-cli 模式），提供**项目初始化**、**组件创建**与**环境配置**能力。
+开发调试由用户项目**本地的** `@bams-app/ui-dev-server` 承担（`npm run dev:ui <环境标识>`），全局 CLI 不参与启动开发服务。
 
 ## 设计思路
 
 `work-cli` 是**薄壳**，不内嵌任何服务/能力包代码（仅内嵌脚手架项目模板 `templates/project/`），
 全部复用 work 仓库发布到 npm 的包：
 
-| 能力 | 来源包 |
-| --- | --- |
-| 项目/组件创建 | `@bams-app/create-ui-component`、`@bams-app/create-ui-page`、`@bams-app/create-ui-base`（内部引用 `@bams-app/ui-*-template`） |
-| 开发服务 / 构建 | `@bams-app/ui-dev-server`（serve / build-app / build-umd） |
-| 环境变量加载 | `@bams-app/shared-env` |
-| 环境配置创建 | `@bams-app/create-env`（交互式生成 `.envs/.env.dev-<alias>`） |
-| 动态入口生成 | `@bams-app/create-pages-entry`（扫描 page-*/ui-* 生成 build-components-entry.js） |
-| 批量页面创建 | `@bams-app/create-pages-from-components`（批量将 ui-* 转为 page-*，复用 create-ui-page） |
-| 公共配置 | `@bams-app/configs`（app-config.json、可配置组件插槽默认值，被 ui-dev-server 与 store 依赖） |
+| 能力          | 来源包                                                                                                                                 |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| 项目/组件创建 | `@bams-app/create-ui-component`、`@bams-app/create-ui-page`、`@bams-app/create-ui-base`（内部引用 `@bams-app/ui-*-template`）          |
+| 开发服务      | `@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>`）                                                                          |
+| 动态入口生成  | `@bams-app/create-pages-entry`（扫描 page-_/ui-_ 生成 build-components-entry.js）                                                      |
+| 批量页面创建  | `@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` 也不会默认创建它们）。
-- 项目根 `package.json` 只声明 `@bams-app/ui-dev-server` 与能力包，**不声明任何外部运行时依赖**；
-  发布后模式下能力包的传递依赖（vue、ant-design-vue 等）由 npm 自动安装。`create` **不生成**
-  项目 `.npmrc`；仅本地验证模式（`file:` 引用 work 本地包）需手动在项目根创建 `.npmrc` 并写入
-  `install-links=true`，否则 npm 只对 `file:` 包建符号链接、不安装其传递依赖。
-- 能力包（`work/packages`、`work/ui`、`work/configs` 下的全部运行时包，含 ui 组件）声明
-  **以 ui-dev-server 的 dependencies 为单一来源**：本地验证模式逐个 `file:` 注入 work 本地
-  目录，发布后模式由 ui-dev-server 的 dependencies 随 npm 自动安装，业务组件与 runtime
-  共用同一份根 node_modules。
-- 所有命令通过 `require.resolve()` 定位 work 包 bin 并以子进程委托执行，`WORK_PROJECT_ROOT` 环境变量注入项目根。
+- 项目根 `package.json` 的 `devDependencies` **只声明 `@bams-app/ui-dev-server` 一个**：
+  能力包（`@bams-app/*`）与运行时依赖（vue、ant-design-vue、devextreme 等）的清单只在
+  ui-dev-server 的 `dependencies` 维护**一处**，安装后提升到项目根 `node_modules`，
+  webpack 的 `resolve.modules` 即指向该处，版本随 ui-dev-server 走。
+  `create` **不生成**项目 `.npmrc`（`@bams-app/*` 默认走官方 npm）。
+- 开发调试**不经过 CLI**：`npm run dev:ui <环境标识> [组件名]` 即项目本地的 `ui-dev-server`
+  （npm 走 `node_modules/.bin`），环境文件由其自行加载，追加的位置参数覆盖默认值。
+- 其余命令通过 `require.resolve()` 定位 work 包 bin 并以子进程委托执行，`WORK_PROJECT_ROOT` 环境变量注入项目根。
 
 ### 整体架构
 
@@ -43,19 +43,20 @@ flowchart LR
         C["@bams-app/*"]
     end
     subgraph CLI["@bams-app/work-cli（全局 CLI）"]
-        D["create / add / dev<br/>env / pages-entry / pages-from-components"]
+        D["create / add / env<br/>pages-entry / pages-from-components"]
     end
     subgraph PROJ["用户项目（Monorepo）"]
-        E["package.json<br/>仅声明 @bams-app/*"]
-        F["npm install<br/>能力包及传递依赖自动安装"]
+        E["package.json<br/>devDependencies：仅 ui-dev-server"]
+        F["npm install<br/>依赖自动安装"]
+        G["npm run dev:ui 环境标识<br/>本地 ui-dev-server"]
     end
     A -->|"publish-all / 单包 npm publish"| C
     B -->|"发布 + 依赖声明"| C
     C -->|"registry 安装"| CLI
-    C -->|"发布后随 npm 自动安装"| PROJ
-    CLI -->|"create 以 file: 注入"| PROJ
+    C -->|"registry 安装（ui-dev-server + 能力包 + 运行时依赖）"| PROJ
     CLI -->|"子进程委托 work 包 bin"| B
     E --> F
+    F --> G
 ```
 
 ```
@@ -84,32 +85,25 @@ bams-work create my-bams-project
 cd my-bams-project
 npm install
 
-# 启动 work 开发环境（加载 .envs/.env.dev-<env>）
-bams-work dev demo                 # 默认组件 ui-component-demo
-bams-work dev demo ui-order-list   # 指定组件
+# 启动开发环境（项目本地 ui-dev-server，环境标识用位置参数传入，不加 -- 分隔符）
+npm run dev:ui demo                    # 加载 .envs/.env.dev-demo + 组件 ui-component-demo
+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
-
-# 升级 @bams-app 包（查询最新版并重装依赖）
-bams-work update
 ```
 
 ### 命令一览
 
-| 命令 | 说明 |
-| --- | --- |
-| `create <name>` | 初始化 Monorepo 项目模版（含示例组件与 `.bams-work/` 标记） |
-| `add --dir <scope> --name <name>` | 在 scope 目录下创建组件（component/page/base），并注册 workspace |
-| `dev <env> [component]` | 启动 work 开发环境（复用 ui-dev-server serve） |
-| `env` | 交互式创建开发环境配置 `.envs/.env.dev-<alias>`（复用 create-env） |
-| `update [--skip-install]` | 升级 `@bams-app` 包：查询最新版本、更新 ui-dev-server 声明并重装依赖 |
-| `pages-entry --dir <dir> --type <page\|component>` | 扫描 page-*/ui-* 目录生成 webpack 动态入口（复用 create-pages-entry） |
-| `pages-from-components --dir <dir>` | 批量将 ui-* 组件转为 page-* 页面（复用 create-pages-from-components） |
-
-> `build`、`umd` 命令暂时下线（入口与示例均已移除），暂不可用。
+| 命令                                               | 说明                                                                  |
+| -------------------------------------------------- | --------------------------------------------------------------------- |
+| `create <name>`                                    | 初始化 Monorepo 项目模版（含示例组件与 `.bams-work/` 标记）           |
+| `add --dir <scope> --name <name>`                  | 在 scope 目录下创建组件（component/page/base），并注册 workspace      |
+| `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） |
 
 ### 组件目录规范
 
@@ -118,8 +112,12 @@ bams-work update
 
 ## 开发环境机制
 
-- `.envs/.env.dev-<env>`：环境配置，`dev <env>` 时由 `@bams-app/shared-env` 加载。
-- 代理：项目根 `.proxy.js`（参考 `.proxy.js.example`）。
+- `.envs/.env.dev-<env>`：环境配置，`npm run dev:ui <env>` 时由项目本地 `ui-dev-server` 加载
+  （复用 `@bams-app/shared-env` 的 `lib/env-loader`，支持 `#` 注释、`export` 前缀、引号、`${VAR}` 引用，
+  以及项目根同名文件覆盖）。
+- 代理：项目根 `.proxy.js`（可选，参考 `.proxy.js.example`）。其中声明的前缀优先于内置默认
+  前缀（`/bams-assets`、`/bams-ui-umd`、`/bams-app`、`/admin-api`、`/preview`，target 取
+  `PROXY_TARGET`）且内置默认仅补充未声明项；键序即匹配序（精确 path 请写在前面），修改后需重启。
 - webpack 扩展：项目根 `vue.config.extend.js`（导出对象或 `({ env, projectRoot }) => 对象`）。
 - 可配置插槽：`COMPONENT_*` 环境变量 + `@configurable/*` 别名（login / header / startr-layout）。
 - 能力包可选组件（未安装时）由 `OPTIONAL_PACKAGE_FALLBACKS` 兜底 alias 到空入口，保证编译不报错。
@@ -157,49 +155,53 @@ cd work/configs && npm publish --registry=https://registry.npmjs.org/
 单包发布只影响该包，其他包版本号不变；需要整体提升版本时使用 `yarn publish-all`。
 发布官方 npm 时 `@bams-app` scope 会随首个 scoped 包自动创建，无需预先注册。
 
-能力包（`@bams-app/*`，含 `work/ui` 下的 ui 组件包）由 `ui-dev-server` 的 dependencies
-统一声明，发布后随 `npm install` 自动安装到用户项目，无需逐包注入。
-
-`work-cli` 与 `create` 生成的项目均以 `"*"` 声明 `@bams-app/*` 依赖：仓库内经 yarn
+`work-cli` 与 `create` 生成的项目均以 `"*"` 声明 `@bams-app/ui-dev-server`：仓库内经 yarn
 workspaces 链接到本地包，发布后自动解析为 registry 上最新的已发布版本，无需手动改版本号。
 
 ## 用户项目升级
 
-用户项目依赖 `@bams-app/*` 的方式决定升级方式：本地验证模式为 `file:` 引用 work 本地包，
-发布后模式仅直接依赖 `@bams-app/ui-dev-server`（`^0.0.1`），能力包由 ui-dev-server 的
-dependencies（`"*"`）传递安装。
-
-### 一键升级（推荐）
+用户项目的 `devDependencies` 只声明 `@bams-app/ui-dev-server` 一个（`"*"`），能力包与
+运行时依赖全部作为它的传递依赖解析到同一份包，提升到项目根 `node_modules`。
 
-```bash
-bams-work update
-```
+### 为什么直接用 npm 命令带不动这些依赖
 
-自动完成：本地 file: 模式清除 node_modules 中的 file: 依赖缓存后重装，强制同步 work 最新
-源码；发布后模式查询 registry 最新版本 → 更新 `package.json` 中 ui-dev-server 声明 →
-重新 `npm install`（能力包 `*` 范围自动对齐最新）。`--skip-install` 可跳过重装。
+能力包在 ui-dev-server 里声明为 `"*"`，运行时依赖是普通版本范围，而项目
+`package-lock.json` 已把它们逐个钉死在具体版本、且仍满足声明范围，npm 便不再重新解析：
+`npm install` 与 `npm update @bams-app/ui-dev-server` 都不会动它们；裸 `npm update` 虽能带上，
+但会重解析整棵依赖树、顺带升级其它第三方依赖。所以只能清掉它们在 lockfile 里的记录，
+让 npm 重新解析。
 
-### 本地验证模式（file:）
-
-需先在项目根创建 `.npmrc` 并写入 `install-links=true`（`create` 不再生成），使能力包以复制
-方式安装并解析其全部传递依赖。npm 对已安装的 file: 依赖会直接跳过（即使源码已变化），
-`bams-work update` 会先清除 node_modules 中全部 file: 依赖缓存再重装，强制重新复制 work
-本地最新源码：
+### 升级步骤
 
 ```bash
-bams-work update
+# 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
 ```
 
-### 发布后模式（registry）
+清理范围必须覆盖 ui-dev-server 声明的**全部**依赖：只删 `@bams-app/*` 的话，能力包会刷新，
+但 vue / axios 等运行时依赖仍停在 lockfile 里的旧版本。
 
-| 场景 | 命令 |
-| --- | --- |
-| 常规升级（同大版本线 0.1.x） | `npm update @bams-app/ui-dev-server` |
-| 跨大版本（0.1 → 0.2） | 改 package.json 为 `"@bams-app/ui-dev-server": "^0.2.0"` 后 `npm install` |
-| 全部能力包强制最新 | `npm update`，或删除 node_modules 与 package-lock.json 后重装 |
-
-`npm update <pkg>` 会把 ui-dev-server 升到其版本范围允许的最新版，并同步更新依赖树中的
-能力包（`"*"` 范围 → 最新）；跨大版本超出 `^` 约束，需手动修改版本号。
+只想升 ui-dev-server 本身、不在意它带的依赖时，直接 `npm i @bams-app/ui-dev-server@latest`。
+跨大版本（0.1 → 0.2）先改 `package.json` 为 `"^0.2.0"`，再执行上面的两步。
 
 ### 前提
 
@@ -208,24 +210,6 @@ bams-work update
   （registry.npmjs.org）；仅在内网隔离、必须走私服时，才在项目 `.npmrc` 手动加
   `@bams-app:registry=https://npm.hedpy.cn/`（私服若存在同名旧版本，会遮蔽官方新版）。
 
-## 本地验证（未发布时）
-
-未发布时通过 `file:` 引用本地 work 包完成端到端验证（`create` 会自动探测 work 仓库根，
-将 ui-dev-server 与能力包以 `file:` 注入项目依赖，无需手动设置环境变量）。
-注意：本地验证模式需自行在项目根创建 `.npmrc` 并写入 `install-links=true`，使 `file:` 包以
-复制方式安装并解析其全部传递依赖；修改 work 包源码后需重新执行 `npm install` 才会生效：
-
-```bash
-yarn install                    # 在仓库根安装（yarn workspaces 链接 work/ 下的本地包）
-cd work/cli && npm link         # 全局链接 bams-work
-
-cd /tmp && rm -rf demo-app
-bams-work create demo-app        # 自动以 file: 引用本地 ui-dev-server 与能力包
-cd demo-app && npm install
-bams-work dev demo               # 应返回 HTTP 200
-bams-work add --dir energy-ui --name ui-order-list
-```
-
 ## 环境要求
 
 - Node.js >= 16.7.0

package/bin/work-cli.js

@@ -9,20 +9,19 @@ const pkg = require('../package.json');
 const COMMANDS = {
     create: '初始化 Monorepo 项目模版',
     add: '在 scope 目录下创建组件（component/page/base）',
-    dev: '启动 work 开发环境（serve，复用 ui-dev-server）',
     env: '创建开发环境配置（.envs/.env.dev-<alias>）',
-    update: '升级 @bams-app 包（更新 ui-dev-server 并重装依赖）',
     'pages-entry': '扫描 page-*/ui-* 目录生成 webpack 动态入口',
     'pages-from-components': '批量将 ui-* 组件转为 page-* 页面'
 };
 
 // 暂时下线的命令：commands/ 下的实现文件保留，恢复时删除此处对应项即可
-const DISABLED_COMMANDS = ['build', 'umd'];
+// dev：开发环境由用户项目本地的 ui-dev-server 启动（npm run dev:ui），CLI 不再承担
+const DISABLED_COMMANDS = ['dev', 'build', 'umd'];
 
 function printUsage() {
     console.log('');
     console.log(colorize('BAMS-Work CLI', 'cyan'), colorize(`v${pkg.version}`, 'gray'));
-    console.log(colorize('复用 work 已发布的包（ui-dev-server / shared-env / create-ui-*）', 'gray'));
+    console.log(colorize('复用 work 已发布的包（create-env / create-ui-*）', 'gray'));
     console.log('');
     console.log(colorize('用法:', 'bold'));
     console.log('  bams-work <command> [options]');
@@ -35,12 +34,13 @@ function printUsage() {
     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 dev demo ui-component-demo    # 启动 work 开发环境');
     console.log('  bams-work env                               # 创建开发环境配置（交互式）');
-    console.log('  bams-work update                            # 升级 @bams-app 包');
     console.log('  bams-work pages-entry --dir energy-ui --type page');
     console.log('  bams-work pages-from-components --dir energy-ui');
     console.log('');
+    console.log(colorize('开发调试:', 'bold'));
+    console.log('  在项目根目录执行 npm run dev:ui <环境标识>（由项目本地 ui-dev-server 启动并加载 .envs/ 环境文件）');
+    console.log('');
 }
 
 async function main() {

package/commands/add.js

@@ -131,7 +131,7 @@ async function main(args) {
     }
 
     success(`组件创建成功: ${toKebabCase(params.name)}（scope: ${scopeDir}）`);
-    info(`开发: bams-work dev <env> ${toKebabCase(params.name)}`);
+    info(`开发: npm run dev:ui <环境标识> -c ${toKebabCase(params.name)}`);
     // UMD 命令暂时下线，恢复后取消注释
     // info(`UMD: bams-work umd ${toKebabCase(params.name)}`);
 }

package/commands/create.js

@@ -1,80 +1,12 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
-const { copyDir, exists, isDirectory, toKebabCase, error, success, info, log } = require('../lib/utils');
+const { copyDir, exists, isDirectory, readJson, writeJson, toKebabCase, error, success, info, log } = require('../lib/utils');
 
 const WORK_CLI_ROOT = path.resolve(__dirname, '../');
 const TEMPLATES_DIR = path.join(WORK_CLI_ROOT, 'templates');
 const PROJECT_TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'project');
 
-/**
- * 探测 work 仓库根目录（本地验证模式定位 file: 引用来源）
- * 1. WORK_PROJECT_ROOT 环境变量优先
- * 2. 通过 file: 安装的 @bams-app/ui-dev-server 包真实路径上溯（ui-dev-server -> tooling -> work -> 仓库根）
- * 3. 均不可用（registry 安装）时返回空，走发布模式
- * @returns {string} work 仓库根目录或空字符串
- */
-function detectWorkRoot() {
-    if (process.env.WORK_PROJECT_ROOT) {
-        return process.env.WORK_PROJECT_ROOT;
-    }
-    try {
-        const pkgPath = require.resolve('@bams-app/ui-dev-server/package.json');
-        const candidate = path.resolve(path.dirname(pkgPath), '../../..');
-        if (isDirectory(path.join(candidate, 'work', 'packages'))) {
-            return candidate;
-        }
-    } catch (e) {
-        // 忽略探测失败，回退发布模式
-    }
-    return '';
-}
-
-/**
- * 生成 ui-dev-server 依赖声明
- * - 本地验证模式（探测到 work 仓库）使用 file: 引用 work 仓库本地包
- * - 否则使用 registry 版本号（发布后模式）
- */
-function buildUiDevServerDep() {
-    const workRoot = detectWorkRoot();
-    if (workRoot) {
-        const pkgDir = path.join(workRoot, 'work', 'tooling', 'ui-dev-server');
-        if (isDirectory(pkgDir)) {
-            return `"@bams-app/ui-dev-server": "file:${pkgDir}"`;
-        }
-    }
-    return `"@bams-app/ui-dev-server": "*"`;
-}
-
-/**
- * 生成能力包依赖声明（单一来源：ui-dev-server 的 dependencies 中 @bams-app/*）
- * - 本地验证模式（探测到 work 仓库）使用 file: 引用 work 仓库本地包（覆盖未发布包）
- * - 发布后模式沿用 ui-dev-server 声明的版本范围，保证与 ui-dev-server 的传递依赖同源，
- *   安装时解析为同一份，避免同一能力包出现两个版本
- */
-function buildCapabilityDeps() {
-    const workRoot = detectWorkRoot();
-    const uiDevServerPkg = require(require.resolve('@bams-app/ui-dev-server/package.json'));
-    return Object.entries(uiDevServerPkg.dependencies || {})
-        .filter(([name]) => name.startsWith('@bams-app/'))
-        .map(([name, range]) => {
-            if (!workRoot) {
-                return `,\n    "${name}": "${range}"`;
-            }
-            const short = name.replace('@bams-app/', '');
-            // 在 work/configs、work/packages、work/ui、work/tooling 多个位置依次查找包目录
-            const pkgDir = short === 'configs' && isDirectory(path.join(workRoot, 'work', 'configs'))
-                ? path.join(workRoot, 'work', 'configs')
-                : [
-                    path.join(workRoot, 'work', 'packages', short),
-                    path.join(workRoot, 'work', 'ui', short),
-                    path.join(workRoot, 'work', 'tooling', short)
-                ].find(dir => isDirectory(dir));
-            return `,\n    "${name}": "file:${pkgDir}"`;
-        })
-        .join('');
-}
-
 /**
  * 委托 @bams-app/create-ui-component 创建示例组件（复用 work 的模板与命令）
  */
@@ -159,13 +91,11 @@ async function main(args) {
         'utf8'
     );
 
-    // 3. 替换项目 package.json 占位符
+    // 3. 生成项目 package.json：替换项目名
     const projectPackageJson = path.join(targetDir, 'package.json');
-    const pkgContent = fs.readFileSync(projectPackageJson, 'utf8')
-        .split('__PROJECT_NAME__').join(projectName)
-        .split('__UI_DEV_SERVER_DEP__').join(buildUiDevServerDep())
-        .split('__CAPABILITY_DEPS__').join(buildCapabilityDeps());
-    fs.writeFileSync(projectPackageJson, pkgContent, 'utf8');
+    const projectPkg = readJson(projectPackageJson);
+    projectPkg.name = projectName;
+    writeJson(projectPackageJson, projectPkg);
 
     // 4. 创建示例组件（复用 work 的 create-ui-component 模板与命令）
     const demoCode = await createDemoComponent(targetDir);
@@ -181,8 +111,9 @@ async function main(args) {
     log(`  cd ${projectName}`);
     log('  npm install            # 或 yarn install（ui-dev-server 与能力包将安装到根 node_modules）');
     log('');
-    log('启动 work 开发环境：');
-    log(`  bams-work dev demo ui-component-demo   # 加载 .envs/.env.dev-demo`);
+    log('启动开发环境（项目本地 ui-dev-server，环境标识用位置参数传入）：');
+    log('  npm run dev:ui demo                    # 加载 .envs/.env.dev-demo + ui-component-demo');
+    log('  npm run dev:ui demo ui-component-demo  # 指定组件（换环境改第 1 个参数）');
     log('');
     log('创建新组件：');
     log('  bams-work add --dir energy-ui --name ui-order-list');

package/commands/dev.js

@@ -5,6 +5,10 @@ const { findProjectRoot, error, info, run } = require('../lib/utils');
 /**
  * 用法: bams-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）：
+ * 开发环境改由用户项目本地承担（模板 package.json 的 dev:ui 脚本 + npm run dev:ui），
+ * 全局 CLI 不再依赖 ui-dev-server / shared-env；如需恢复本命令，需同时恢复这两个依赖。
  */
 async function main(args) {
     const projectRoot = findProjectRoot(process.cwd());

package/package.json

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

package/templates/project/.proxy.js.example

@@ -1,6 +1,15 @@
 /**
  * BAMS-Work 自定义开发代理（可选）
- * 存在本文件时自动生效，覆盖内置默认代理前缀。
+ * 存在本文件（去掉 .example 后缀）时由 ui-dev-server 自动加载。
+ *
+ * 优先级（同名前缀由前者覆盖后者）：
+ *   1. 本文件 proxy 中声明的前缀
+ *   2. 内置默认前缀 /bams-assets、/bams-ui-umd、/bams-app、/admin-api、/preview
+ *      （target 取环境文件中的 PROXY_TARGET，仅补充本文件未声明的前缀）
+ *
+ * 键序即匹配序：webpack-dev-server 按声明顺序匹配，精确 path 请写在前面。
+ * 修改后需重启开发服务（npm run dev:ui）才生效。
+ *
  * 也可导出函数：module.exports = ({ env, projectRoot }) => ({ proxy: { ... } })
  */
 module.exports = {

package/templates/project/README.md

@@ -19,40 +19,48 @@
 ## 快速开始
 
 ```bash
-npm install            # 安装依赖到根 node_modules
-bams-work dev demo     # 启动开发环境（示例环境端口 8700）
+npm install            # 安装依赖到根 node_modules（含项目本地的 ui-dev-server）
+npm run dev:ui demo    # 启动开发环境（环境标识 demo → .envs/.env.dev-demo，示例端口 8700）
 ```
 
-> 所有 `bams-work` 命令都在**项目根目录**执行（即含 `.bams-work/` 的目录）。
-> 全局帮助 `bams-work --help`，查看版本 `bams-work --version`。
+> 开发调试由**项目本地**的 `@bams-app/ui-dev-server` 启动（`npm run dev:ui <环境标识>`），
+> 环境标识作为位置参数传入（`demo` → `.envs/.env.dev-demo`）。
+> 其余 `bams-work` 命令都在**项目根目录**（含 `.bams-work/` 的目录）执行。
+> 全局帮助 `bams-work --help`，版本 `bams-work --version`。
 
 ## 命令一览
 
 | 命令                                                 | 作用                        |
 | ---------------------------------------------------- | --------------------------- |
-| `dev <env> [component]`                              | 启动开发服务（最常用）      |
+| `npm run dev:ui <环境标识>`                          | 启动开发服务（最常用）      |
 | `add --dir <scope> --name <name>`                    | 新建组件 / 页面 / 基础组件  |
 | `env`                                                | 交互式创建开发环境配置      |
-| `update`                                             | 升级 `@bams-app` 依赖       |
 | `pages-entry --dir <scope> --type <page\|component>` | 生成 webpack 动态入口       |
 | `pages-from-components --dir <scope>`                | 批量将 `ui-*` 转为 `page-*` |
 
-### 1. `bams-work dev` — 启动开发环境
+### 1. `npm run dev:ui <环境标识>` — 启动开发环境
+
+`dev:ui` 即项目本地的 `ui-dev-server`，**环境标识用位置参数指定（不加 `--` 分隔符）**，
+追加的位置参数会覆盖默认值：
 
 ```bash
-bams-work dev demo                              # 加载 .envs/.env.dev-demo，默认组件 ui-component-demo
-bams-work dev demo ui-order-list                # 指定要调试的组件
-bams-work dev demo ui-order-list --layout touch # 切换布局（默认 pc）
-bams-work dev demo ui-order-list -- --port 8080 # `--` 之后的参数透传给 vue-cli-service
+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
 ```
 
-| 参数                | 必填 | 说明                                                                                   |
-| ------------------- | ---- | -------------------------------------------------------------------------------------- |
-| `<env>`             | 是   | 环境标识，对应 `.envs/.env.dev-<env>`；文件不存在会直接报错，先用 `bams-work env` 创建 |
-| `[component]`       | 否   | 组件目录名（如 `ui-order-list`），省略时默认 `ui-component-demo`                       |
-| `--layout`、`-l`    | 否   | 布局：`pc`（默认）/ `touch`                                                            |
-| `--component`、`-c` | 否   | 等价于位置参数 `[component]`                                                           |
-| `--` 之后的参数     | 否   | 原样透传给底层 `vue-cli-service`（如 `--port`、`--open`）                              |
+| 参数                | 必填 | 说明                                                               |
+| ------------------- | ---- | ------------------------------------------------------------------ |
+| 位置参数 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` 决定后端代理目标。
 
@@ -71,7 +79,7 @@ bams-work add --dir demo-ui --name ui-base-btn --type base        # 基础组件
 | `--type` | 否   | `component`（默认）/ `page` / `base`                                                                                    |
 | `--desc` | 否   | 组件描述                                                                                                                |
 
-创建完成后会提示用哪条 `dev` 命令调试。
+创建完成后会提示用哪条 `npm run dev:ui` 命令调试。
 
 ### 3. `bams-work env` — 创建开发环境
 
@@ -88,7 +96,7 @@ bams-work env
 - **快速复制**：基于现有环境文件，或 `production` 空值模板，只改差异项（推荐）
 - **自定义配置**：从默认模板逐项填写
 
-环境标识即 `dev` 的第一个参数：`bams-work env` 创建了 `test`，就用 `bams-work dev test` 启动。
+环境标识即 `npm run dev:ui` 的第 1 个位置参数：`bams-work env` 创建了 `test`，就用 `npm run dev:ui test` 启动。
 
 常用字段（可直接编辑对应环境文件，`dev` 每次启动都会重新加载）：
 
@@ -106,12 +114,41 @@ bams-work env
 | `VUE_APP_LOGIN_URL`、`VUE_APP_LOGIN_PUBLIC_KEY`、`VUE_APP_WEBSOCKET_URL`                    | 登录页地址、登录公钥、WebSocket 地址                 |
 | `VUE_APP_DEVEXTREME_LICENSE_KEY`                                                            | DevExtreme 许可证密钥（可留空）                      |
 
-### 4. `bams-work update` — 升级依赖
+### 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 的声明重新解析：
 
 ```bash
-bams-work update                  # 升级并重装依赖
+# 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
 ```
 
+只想升 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`（构建流程内部使用，一般无需手动执行）
@@ -121,13 +158,12 @@ bams-work update                  # 升级并重装依赖
 
 ```bash
 npm install
-# 或
-yarn install
 ```
 
-`@bams-app/ui-dev-server` 及其依赖的能力包（`@bams-app/components` 等）会安装到根 node_modules，
-业务组件与 work 开发环境共用同一套能力实例；能力包的传递依赖（vue、ant-design-vue 等）由 npm
-自动安装，因此 `package.json` 无需声明任何外部运行时依赖。
+项目只声明 `@bams-app/ui-dev-server` 一个开发依赖，能力包（`@bams-app/components` 等）与
+运行时依赖（vue、ant-design-vue、devextreme、pinia、axios、dayjs 等）都由它提供，
+安装后提升到项目根 `node_modules`，业务组件与开发环境共用同一份实例。升级这些依赖只需
+更新 ui-dev-server（见上文），无需逐个改版本号。
 
 ## 升级 CLI
 
@@ -135,10 +171,12 @@ yarn install
 npm i -g @bams-app/work-cli@latest
 ```
 
-项目运行时依赖只有 `@bams-app/ui-dev-server`，其余能力包（`@bams-app/components` 等）由它传递安装，
-升级项目依赖用 `bams-work update`（见上文）。
+全局 CLI 只负责创建项目、组件与环境配置，开发调试由项目本地的 `npm run dev:ui` 承担；
+项目依赖按上文「升级 ui-dev-server 提供的依赖」清理 lockfile 后升级。
 
 ## 自定义配置
 
-- 代理：创建项目根 `.proxy.js`（见 `.proxy.js.example`）
+- 代理：创建项目根 `.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 }) => 对象`）

package/templates/project/gitignore.tpl

@@ -6,9 +6,6 @@ dist/
 build/
 *.log
 
-# BAMS-Work 内部产物（install 时由 .bams-work 重新生成）
-.bams-work/
-
 # IDE
 .vscode/
 .idea/

package/templates/project/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "__PROJECT_NAME__",
+  "name": "bams-work-project",
   "version": "0.0.6",
   "private": true,
   "description": "BAMS-Work Monorepo 项目",
@@ -11,26 +11,10 @@
     "bams-ui"
   ],
   "scripts": {
-    "dev": "bams-work dev",
+    "dev:ui": "ui-dev-server",
     "add": "bams-work add"
   },
-  "dependencies": {
-    __UI_DEV_SERVER_DEP____CAPABILITY_DEPS__,
-    "@ant-design/icons-vue": "^7.0.1",
-    "ant-design-vue": "4.2.6",
-    "axios": "^1.13.2",
-    "core-js": "^3.8.3",
-    "dayjs": "^1.11.20",
-    "devextreme": "25.2.3",
-    "devextreme-exceljs-fork": "^4.4.8",
-    "devextreme-vue": "25.2.3",
-    "file-saver": "^2.0.5",
-    "flex.css": "^1.1.7",
-    "jsencrypt": "^3.5.4",
-    "marked": "^17.0.4",
-    "pinia": "^3.0.4",
-    "pinia-plugin-persistedstate": "^4.7.1",
-    "vue": "^3.5.24",
-    "vue-router": "4"
+  "devDependencies": {
+    "@bams-app/ui-dev-server": "*"
   }
 }

package/commands/update.js

@@ -1,119 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { findProjectRoot, readJson, writeJson, run, error, warn, success, info, log } = require('../lib/utils');
-
-const UI_DEV_SERVER = '@bams-app/ui-dev-server';
-
-// 解析版本范围中声明的基础版本（如 ^0.1.0 -> 0.1.0）
-function parseRangeVersion(range) {
-    if (!range) return null;
-    const match = String(range)
-        .replace(/^[~^]/, '')
-        .match(/(\d+)\.(\d+)\.(\d+)/);
-    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
-}
-
-// 简单三段的版本比较：a > b 返回 1，相等 0，小于 -1
-function compareVersions(a, b) {
-    const pa = a.split('.').map(Number);
-    const pb = b.split('.').map(Number);
-    for (let i = 0; i < 3; i++) {
-        if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-        if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-    }
-    return 0;
-}
-
-// 查询 registry 上的最新版本（继承项目 .npmrc 的 @bams-app:registry 配置）
-function fetchLatestVersion(projectRoot) {
-    try {
-        const output = execSync(`npm view ${UI_DEV_SERVER} version --no-audit --no-fund`, {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore']
-        });
-        return String(output).trim() || null;
-    } catch (e) {
-        return null;
-    }
-}
-
-async function main(args) {
-    const skipInstall = args.includes('--skip-install');
-    const projectRoot = findProjectRoot();
-    if (!projectRoot) {
-        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请在用户项目根目录执行');
-        process.exit(1);
-    }
-
-    const pkgPath = path.join(projectRoot, 'package.json');
-    const pkg = readJson(pkgPath);
-    const declared = (pkg.dependencies || {})[UI_DEV_SERVER];
-
-    if (!declared) {
-        warn(`未在 package.json 中找到 ${UI_DEV_SERVER} 依赖`);
-        process.exit(0);
-    }
-
-    // 本地验证模式：file: 引用，升级 = 清除缓存 + 重装以同步 work 最新源码
-    if (declared.startsWith('file:')) {
-        if (skipInstall) {
-            warn('本地验证模式需重装才能同步源码，忽略 --skip-install');
-        }
-        info(`当前为本地验证模式（${declared}）`);
-        // npm 对已安装的 file: 依赖会直接跳过（即使源码已变化），
-        // 需先清除 node_modules 中的安装缓存，再重装强制重新复制
-        const fileDeps = Object.entries(pkg.dependencies || {})
-            .filter(([, v]) => typeof v === 'string' && v.startsWith('file:'))
-            .map(([name]) => name);
-        let removed = 0;
-        for (const name of fileDeps) {
-            const target = path.join(projectRoot, 'node_modules', name);
-            try {
-                if (fs.lstatSync(target)) {
-                    fs.rmSync(target, { recursive: true, force: true });
-                    removed++;
-                }
-            } catch (e) {
-                // 目标不存在，跳过
-            }
-        }
-        info(`已清除 ${removed} 个 file: 依赖缓存，将重新同步 work 源码`);
-    } else {
-        // 发布后模式：查询 registry 最新版本并升级声明
-        const current = parseRangeVersion(declared);
-        const latest = fetchLatestVersion(projectRoot);
-        if (!latest) {
-            warn(`查询 ${UI_DEV_SERVER} 最新版本失败（请检查项目 .npmrc 的 @bams-app:registry 配置与网络）`);
-        } else if (current && compareVersions(latest, current) > 0) {
-            info(`发现新版本: ${current} -> ${latest}`);
-            pkg.dependencies[UI_DEV_SERVER] = `^${latest}`;
-            writeJson(pkgPath, pkg);
-            success(`已更新 ${UI_DEV_SERVER} 为 ^${latest}`);
-        } else {
-            info(`${UI_DEV_SERVER} 已是最新版本（${latest}）`);
-        }
-        if (skipInstall) {
-            info('已跳过依赖安装（--skip-install），请手动执行 npm install');
-            process.exit(0);
-        }
-    }
-
-    log('正在重新安装依赖（能力包为 * 范围，将自动对齐最新版）...');
-    const code = await run('npm', ['install'], { cwd: projectRoot });
-    if (code !== 0) {
-        error('依赖安装失败');
-        process.exit(code);
-    }
-    success('升级完成');
-}
-
-module.exports = main;
-
-if (require.main === module) {
-    main(process.argv.slice(2)).catch((err) => {
-        error(err.message || err);
-        process.exit(1);
-    });
-}