@bams-app/work-cli 0.1.5 → 0.1.6

package/README.md

@@ -104,6 +104,29 @@ work add --dir demo-ui --name ui-base-btn --type base
 | `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） |
+| `skills sync`                                      | 把已安装组件包内嵌的 `SKILL.md` 同步到项目根 `.skills/`（与 AI 工具无关） |
+
+### 组件技能分发
+
+组件包（`@bams-app/ui-*`、`@bams-app/permission`、`@bams-app/theme` 等）各自内嵌一份 `SKILL.md`，
+随 npm 包一起发布，是技能内容的**唯一真源**。
+
+```bash
+# 项目安装依赖后（模板的 postinstall 已自动执行一次），也可手动同步
+work skills sync              # 同步到 <项目根>/.skills/<skill-name>/{SKILL.md,references/}
+work skills sync --dry-run    # 只列出将要同步的技能
+work skills sync --force      # 内容一致时也重新复制
+```
+
+`.skills/` 采用标准 Agent Skills 目录结构，**不绑定任何 AI 工具**，脚本不会写入 `.trae/skills/`、
+`.claude/skills/`、`.cursor/rules/` 等任何工具私有目录。使用者按自己用的工具自行安装，
+例如 Trae 与 Claude Code 属于同一套规范，直接复制目录即可，其他工具让各自的 AI 现场转换格式。
+
+`work skills sync` 是幂等的：内容一致则跳过。修改技能时请改**组件包内的 `SKILL.md`**，
+再重跑同步，避免 `.skills/` 与包内两份内容漂移。
+
+命令只在明确的项目根下工作：优先用 `--root <dir>`，否则向上查找 `work create` 生成的 `.bams-work`
+标记目录，**找不到即中止报错**（不会兜底到当前目录），以免在错误位置意外生成 `.skills/`。
 
 ### 组件目录规范
 

package/bin/work-cli.js

@@ -11,7 +11,8 @@ const COMMANDS = {
     add: '在 scope 目录下创建组件（component/page/base）',
     env: '创建开发环境配置（.envs/.env.dev-<alias>）',
     'pages-entry': '扫描 page-*/ui-* 目录生成 webpack 动态入口',
-    'pages-from-components': '批量将 ui-* 组件转为 page-* 页面'
+    'pages-from-components': '批量将 ui-* 组件转为 page-* 页面',
+    skills: '把组件包内嵌的 SKILL.md 同步到项目根 .skills/（中立目录，与 AI 工具无关）'
 };
 
 // 暂时下线的命令：commands/ 下的实现文件保留，恢复时删除此处对应项即可
@@ -37,6 +38,7 @@ function printUsage() {
     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('  work skills sync                        # 把组件包内嵌技能同步到 .skills/');
     console.log('');
     console.log(colorize('开发调试:', 'bold'));
     console.log('  在项目根目录执行 npm run dev:ui <环境标识>（由项目本地 ui-dev-server 启动并加载 .envs/ 环境文件）');

package/commands/skills.js

@@ -0,0 +1,226 @@
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot, isDirectory, error, warn, success, info, colorize } = require('../lib/utils');
+
+/**
+ * 用法: work skills sync [--root <dir>] [--dry-run] [--force] [--quiet]
+ *
+ * 把已安装的 @bams-app/* 组件包内嵌的 SKILL.md 同步到项目根的中立目录 .skills/。
+ * .skills/ 使用标准 Agent Skills 目录结构（<skill-name>/SKILL.md + references/），
+ * 不绑定任何 AI 工具，由使用者自行安装到各自的工具目录（.trae/skills、.claude/skills、
+ * .cursor/rules 等），因此本命令不写入任何工具私有目录。
+ */
+function parseArgs(args) {
+    const params = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            params[key] = next;
+            i++;
+        } else {
+            params[key] = true;
+        }
+    }
+    return params;
+}
+
+/**
+ * 解析 SKILL.md frontmatter 的 name 字段
+ */
+function readSkillName(skillFile) {
+    const content = fs.readFileSync(skillFile, 'utf8');
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        return null;
+    }
+    const line = match[1].match(/^name:[ \t]*(.+)$/m);
+    if (!line) {
+        return null;
+    }
+    return line[1].trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * 收集需要同步的文件（SKILL.md + references/ 下的全部文件），返回 [相对路径] 列表
+ */
+function collectSkillFiles(packageDir) {
+    const files = ['SKILL.md'];
+    const referencesDir = path.join(packageDir, 'references');
+    if (isDirectory(referencesDir)) {
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath);
+                } else {
+                    files.push(path.relative(packageDir, fullPath));
+                }
+            }
+        };
+        walk(referencesDir);
+    }
+    return files;
+}
+
+function isUpToDate(packageDir, targetDir, files) {
+    return files.every((relative) => {
+        const src = path.join(packageDir, relative);
+        const dest = path.join(targetDir, relative);
+        if (!fs.existsSync(dest)) {
+            return false;
+        }
+        return fs.readFileSync(src, 'utf8') === fs.readFileSync(dest, 'utf8');
+    });
+}
+
+/**
+ * 扫描 @bams-app 作用域下的包，返回 [{ directory, dir }]
+ */
+function scanInstalledPackages(projectRoot) {
+    const scopeDir = path.join(projectRoot, 'node_modules', '@bams-app');
+    if (!isDirectory(scopeDir)) {
+        return null;
+    }
+    const result = [];
+    for (const entry of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+        // workspace 场景下 @bams-app/* 是软链，Dirent.isDirectory() 为 false，需用 stat 跟随软链判断
+        const packageDir = path.join(scopeDir, entry.name);
+        if (!isDirectory(packageDir)) {
+            continue;
+        }
+        if (fs.existsSync(path.join(packageDir, 'SKILL.md'))) {
+            result.push({ directory: entry.name, dir: packageDir });
+        }
+    }
+    return result;
+}
+
+function syncSkills(args) {
+    const params = parseArgs(args);
+    const dryRun = params['dry-run'] === true;
+    const force = params.force === true;
+    const quiet = params.quiet === true;
+
+    // 只在明确的项目根下工作：--root 显式指定，或用 work create 生成的 .bams-work 标记定位。
+    // 不做 cwd 兜底，避免在任意目录意外生成 .skills/
+    const projectRoot = params.root ? path.resolve(params.root) : findProjectRoot();
+    if (!projectRoot) {
+        error('未找到项目根目录（向上未发现 .bams-work 标记），请用 --root <dir> 显式指定');
+        return 1;
+    }
+    if (!isDirectory(projectRoot)) {
+        error(`项目根目录不存在: ${projectRoot}`);
+        return 1;
+    }
+
+    info(`项目根目录: ${projectRoot}`);
+
+    const packages = scanInstalledPackages(projectRoot);
+    if (packages === null) {
+        warn(`未找到 ${path.join(projectRoot, 'node_modules', '@bams-app')}，请先执行 npm install`);
+        return 0;
+    }
+    if (packages.length === 0) {
+        warn('node_modules/@bams-app 下没有任何内嵌 SKILL.md 的包，无需同步');
+        return 0;
+    }
+
+    const skillsRoot = path.join(projectRoot, '.skills');
+    const summary = { synced: 0, skipped: 0, failed: 0 };
+
+    for (const pkg of packages) {
+        let skillName;
+        try {
+            skillName = readSkillName(path.join(pkg.dir, 'SKILL.md'));
+        } catch (err) {
+            error(`读取 ${pkg.directory}/SKILL.md 失败: ${err.message}`);
+            summary.failed++;
+            continue;
+        }
+        if (!skillName) {
+            warn(`${pkg.directory}/SKILL.md 缺少 frontmatter name，已跳过（skill 名需与输出目录名一致）`);
+            summary.failed++;
+            continue;
+        }
+
+        const files = collectSkillFiles(pkg.dir);
+        const targetDir = path.join(skillsRoot, skillName);
+
+        if (!force && isUpToDate(pkg.dir, targetDir, files)) {
+            summary.skipped++;
+            if (!quiet) {
+                info(`已是最新: ${skillName}`);
+            }
+            continue;
+        }
+
+        if (dryRun) {
+            summary.synced++;
+            console.log(`  ${colorize('待同步', 'yellow')} ${skillName}  <-  ${pkg.directory}（${files.length} 个文件）`);
+            continue;
+        }
+
+        try {
+            for (const relative of files) {
+                const dest = path.join(targetDir, relative);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.copyFileSync(path.join(pkg.dir, relative), dest);
+            }
+            summary.synced++;
+            if (!quiet) {
+                success(`已同步: ${skillName}`);
+            }
+        } catch (err) {
+            error(`同步 ${skillName} 失败: ${err.message}`);
+            summary.failed++;
+        }
+    }
+
+    console.log('');
+    const parts = [`同步 ${summary.synced} 个`, `已是最新 ${summary.skipped} 个`];
+    if (summary.failed > 0) {
+        parts.push(`失败 ${summary.failed} 个`);
+    }
+    if (dryRun) {
+        console.log('（演练模式，未写入文件）');
+    }
+    console.log(`技能目录: ${skillsRoot}`);
+    console.log(parts.join(' / '));
+    return 0;
+}
+
+/**
+ * 用法: work skills sync
+ */
+module.exports = async function skills(args) {
+    const [subCommand, ...rest] = args;
+
+    if (!subCommand || subCommand === '--help' || subCommand === '-h' || subCommand === 'help') {
+        console.log('');
+        console.log(colorize('用法:', 'bold'));
+        console.log('  work skills sync [--root <dir>] [--dry-run] [--force] [--quiet]');
+        console.log('');
+        console.log('作用: 把已安装的 @bams-app/* 组件包内嵌的 SKILL.md 同步到项目根 .skills/');
+        console.log('      该目录是标准 Agent Skills 结构，与具体 AI 工具无关，由使用者自行安装');
+        console.log('');
+        console.log(colorize('参数:', 'bold'));
+        console.log('  --root <dir>   指定项目根目录（默认向上查找 .bams-work 标记目录，找不到则中止）');
+        console.log('  --dry-run      只列出将要同步的技能，不写入文件');
+        console.log('  --force        内容一致时也重新复制');
+        console.log('  --quiet        只输出汇总，不逐个打印');
+        console.log('');
+        return 0;
+    }
+
+    if (subCommand !== 'sync') {
+        error(`未知子命令: ${subCommand}（可选: sync）`);
+        return 1;
+    }
+
+    return syncSkills(rest);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bams-app/work-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "BAMS-Work 全局开发工具：复用 work 已发布的包（create-env / create-ui-*）提供项目初始化、组件创建与环境配置能力，开发调试由用户项目本地的 ui-dev-server 承担",
   "main": "index.js",
   "bin": {

package/templates/project/README.md

@@ -8,14 +8,16 @@
 package.json                # 项目根配置
 .bams-work/                 # 项目标记目录，勿删
 .envs/                      # 环境配置 .env.dev-<env>
+.skills/                    # 组件技能说明（npm install 自动同步，见下文）
 .proxy.js                   # 自定义代理（可选）
 demo-ui/ui-component-demo   # 示例组件
-<scope>-ui/ui-xxx           # 业务组件（add 时创建）
+<scope>-ui/ui-xxx           # 业务组件（npm run add:component 时创建）
 ```
 
 ## 前置条件（必需）
 
-必须先全局安装 CLI，否则 `work` 命令（`work add` / `work env` / `work pages-entry`）不可用：
+项目内所有能力都以 npm script 形式提供，底层调用全局 CLI `@bams-app/work-cli`，
+因此必须先全局安装（否则 `npm run add:component` 等会提示 command not found）：
 
 ```bash
 npm i -g @bams-app/work-cli
@@ -40,13 +42,14 @@ npm run dev:ui demo -- --port 8080          # `--` 之后透传给 vue-cli-servi
 
 ## 命令
 
-| 命令                                                                               | 作用                                                                        |
-| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `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-*`                                               |
+| 命令                                                                                               | 作用                                                                        |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `npm run dev:ui <环境标识> [组件名]`                                                               | 启动开发服务                                                                |
+| `npm run add:component -- --dir <scope> --name <name> [--type component\|page\|base] [--desc ...]` | 新建组件/页面/基础组件；scope 目录不存在会自动创建并注册到根 `package.json` |
+| `npm run create:env`                                                                               | 交互式生成 `.envs/.env.dev-<标识>`                                          |
+| `npm run sync:skills`                                                                              | 把已安装组件包内嵌的技能同步到 `.skills/`（见下文）                         |
+
+`--` 之后的参数会透传给底层 CLI。
 
 环境文件字段：`PORT`、`PROXY_TARGET`、`BASE_URL`、`VUE_APP_*` 等，见模板文件；改完重跑 `dev:ui` 生效。
 
@@ -67,3 +70,31 @@ npm i @bams-app/ui-dev-server@latest
 
 - 代理：项目根 `.proxy.js`（参考 `.proxy.js.example`），声明的前缀优先于内置默认，修改后需重启
 - webpack：项目根 `vue.config.extend.js`，导出对象或 `({ env, projectRoot }) => 对象`
+
+## 安装其他组件包
+
+业务组件包以 git 仓库形式提供，clone 到项目根目录后执行 `npm i` 即可，不需要修改根 `package.json`：
+
+```bash
+cd <项目根目录>
+git clone https://git.cnbmtech.com/CNBM-CIMS/products/bams-apex/apex-web.git
+npm i
+```
+
+根 `package.json` 的 `workspaces` 已声明 `demo-ui/*`、`bams-components/*`、`*-ui/*`、`apex-web/*`、`bams-ui`，
+clone 后的目录落在这些范围内即可被自动识别，随后 `npm run dev:ui demo ui-order-list` 就能加载其中的组件。
+
+后续更新：进对应仓库目录 `git pull`，再回项目根目录执行 `npm i`。
+
+## 组件技能（AI Skill）
+
+每个组件包内嵌了一份 `SKILL.md` 技能说明，`npm install` 时已自动同步到项目根 `.skills/`，也可手动刷新：
+
+```bash
+npm run sync:skills          # 幂等：内容一致自动跳过
+npm run sync:skills -- --dry-run   # 只看会同步哪些，不写文件
+```
+
+`.skills/` 是标准 Agent Skills 目录（`<skill-name>/SKILL.md`，可带 `references/`），**不绑定任何 AI 工具**：把需要的技能目录复制到你所用工具的规则目录即可，例如 Trae / Claude Code 的 `.trae/skills`、`.claude/skills`；其他工具按其格式转换。升级组件包后重跑一次 `npm run sync:skills` 即刷新内容。
+
+`.skills/` 建议提交到仓库，团队共享同一份技能说明。

package/templates/project/package.json

@@ -12,7 +12,10 @@
   ],
   "scripts": {
     "dev:ui": "ui-dev-server",
-    "add": "work add"
+    "add:component": "work add",
+    "create:env": "work env",
+    "sync:skills": "work skills sync",
+    "postinstall": "work skills sync --quiet || exit 0"
   },
   "dependencies": {
     "@bams-app/bams-components": "*"