lcap-frontend-library 0.0.1

package/README.md

@@ -0,0 +1,271 @@
+# lcap-frontend-library
+
+> LCAP 前端扩展组件库 AI Skill 分发 CLI —— 将领域知识注入 AI 编码助手
+
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![npm](https://img.shields.io/badge/npm-lcap--frontend--library-blue)](https://www.npmjs.com/package/lcap-frontend-library)
+
+---
+
+## 这是什么
+
+`lcap-frontend-library` 是一个 npm CLI 工具，将 LCAP 前端扩展组件库的 AI Skill（结构化 Markdown 指令集）部署到 AI 编码助手的 skill 目录中。
+
+**核心理念**：AI Skill as npm package —— 安装即部署，升级即同步。同一份 Skill 内容通过路径映射适配 Claude Code、Cursor、Codex 三个平台，无需任何平台专有 API。
+
+---
+
+## 快速开始
+
+```bash
+# 部署 Skill 到 AI 工具目录
+npx lcap-frontend-library init
+
+# 交互选择：安装范围（项目/全局）+ 目标工具（claude/cursor/codex）
+
+# 在 AI 工具中使用 —— 输入自然语言即可
+# 「生成一个二维码组件」
+# 「把这个库从 Vue2 迁移到 Vue3」
+```
+
+验证安装：
+
+```bash
+ls .claude/skills/lcap-frontend-library/SKILL.md
+cat .lcap-skill.json
+```
+
+---
+
+## CLI 命令
+
+### `init`
+
+首次部署 Skill。
+
+```bash
+npx lcap-frontend-library init [options]
+```
+
+| 选项 | 说明 | 示例 |
+|------|------|------|
+| `--tools <list>` | 指定目标工具（逗号分隔） | `--tools claude,cursor` |
+| `--global` | 部署到全局目录（`~/.{tool}/skills/`） | `--global` |
+| `--all` | 部署到所有支持的工具 | `--all` |
+
+**行为**：
+- 无 flag + TTY：交互模式（select + checkbox）
+- 无 flag + 非 TTY（CI）：自动部署所有工具，项目级
+- 已安装时：提示使用 `sync`
+
+### `sync`
+
+更新已部署的 Skill 到最新版本。
+
+```bash
+npx lcap-frontend-library sync [options]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--tools <list>` | 覆盖同步目标（默认同步所有已安装工具） |
+
+**行为**：
+1. 读取 `.lcap-skill.json` 获取安装信息
+2. 删除旧 skill 目录 → 复制最新内容
+3. 保留 `LEARNINGS.md`（含 `### LEARN-` 标记时）
+4. 更新 marker 版本号
+
+---
+
+## 架构
+
+```
+lcap-frontend-library/
+├── bin/
+│   └── lcap-frontend-library.mjs   # CLI 入口（ESM shebang）
+├── src/
+│   ├── index.ts                     # Commander 程序定义（init + sync）
+│   ├── init.ts                      # 初始化逻辑（交互/flag/非TTY 三路径）
+│   ├── sync.ts                      # 同步逻辑（删旧→复新→恢复 LEARNINGS）
+│   └── utils.ts                     # 工具函数（路径映射、文件操作、marker 读写）
+├── skill/                           # AI Skill 内容（随包分发）
+│   ├── SKILL.md                     # 顶层路由分发器
+│   ├── LEARNINGS.md                 # 经验库
+│   ├── commands/                    # 13 个阶段命令
+│   ├── workflows/                   # 流程编排（create/evolve/migrate/harness）
+│   ├── references/                  # 领域知识库
+│   ├── templates/                   # 输出格式模板
+│   └── scripts/                     # 脚手架脚本（bash + node）
+├── dist/                            # TypeScript 编译产物
+├── package.json
+└── tsconfig.json
+```
+
+### 技术栈
+
+| 依赖 | 用途 |
+|------|------|
+| `commander` ^12 | CLI 命令框架 |
+| `@inquirer/prompts` ^7 | 交互式选择 |
+| `typescript` ^5.5 | 类型安全 + 编译 |
+
+### 分发模型
+
+```
+上游 Skill 源（monorepo）
+        │  npm run sync-skill
+        ▼
+npm 包（skill/ 目录）
+        │  npx lcap-frontend-library init/sync
+        ▼
+用户项目 AI 工具目录
+  .claude/skills/lcap-frontend-library/
+  .cursor/skills/lcap-frontend-library/
+  .codex/skills/lcap-frontend-library/
+```
+
+---
+
+## 多平台适配
+
+### 路径映射
+
+在 `src/utils.ts` 中定义：
+
+```typescript
+export const TOOL_PATHS: Record<string, string> = {
+  claude: `.claude/skills/${SKILL_NAME}`,
+  cursor: `.cursor/skills/${SKILL_NAME}`,
+  codex: `.codex/skills/${SKILL_NAME}`,
+};
+
+export const GLOBAL_TOOL_PATHS: Record<string, string> = {
+  claude: path.join(os.homedir(), '.claude', 'skills', SKILL_NAME),
+  cursor: path.join(os.homedir(), '.cursor', 'skills', SKILL_NAME),
+  codex: path.join(os.homedir(), '.codex', 'skills', SKILL_NAME),
+};
+```
+
+### 添加新平台
+
+仅需在 `TOOL_PATHS` 和 `GLOBAL_TOOL_PATHS` 中添加条目：
+
+```typescript
+windsurf: `.windsurf/skills/${SKILL_NAME}`,
+```
+
+`init.ts` 和 `sync.ts` 动态读取 key，无需额外修改。
+
+### 平台路径对照
+
+| 工具 | 项目级 | 全局级 |
+|------|--------|--------|
+| claude | `.claude/skills/lcap-frontend-library/` | `~/.claude/skills/lcap-frontend-library/` |
+| cursor | `.cursor/skills/lcap-frontend-library/` | `~/.cursor/skills/lcap-frontend-library/` |
+| codex | `.codex/skills/lcap-frontend-library/` | `~/.codex/skills/lcap-frontend-library/` |
+
+---
+
+## Marker 文件
+
+`.lcap-skill.json` 记录安装状态：
+
+```typescript
+interface Marker {
+  version: string;       // npm 包版本
+  tools: string[];       // 已部署的工具列表
+  scope: 'global' | 'project';
+  installedAt: string;   // ISO 时间戳
+}
+```
+
+- 项目级：写入项目根目录
+- 全局级：写入 `~/`
+- `init` 检查此文件防止重复安装
+- `sync` 依赖此文件确定同步目标
+
+---
+
+## 开发
+
+### 环境准备
+
+```bash
+git clone <repo-url>
+cd npm/lcap-frontend-library
+npm install
+npm run build
+```
+
+### 本地测试
+
+```bash
+# 直接运行
+node bin/lcap-frontend-library.mjs init --tools claude
+
+# 或 npm link
+npm link
+lcap-frontend-library init
+```
+
+### Skill 内容更新
+
+```bash
+# 从上游 monorepo 同步 Skill 源
+npm run sync-skill
+
+# 验证后发布
+npm version patch
+npm publish
+```
+
+用户通过 `npx lcap-frontend-library sync` 获取更新。
+
+### 项目构建
+
+```bash
+npm run build    # TypeScript 编译到 dist/
+npm run prepare  # publish 前自动触发 build
+```
+
+---
+
+## Skill 能力概览
+
+部署后，AI 工具获得以下能力：
+
+| 工作流 | 触发词 | 产出 |
+|--------|--------|------|
+| **Create** | 生成、新建、创建 | 完整可构建 LCAP 项目 + ZIP 产物 |
+| **Evolve** | 修改、增强、更新 | 增量功能 + 零回归保证 |
+| **Migrate** | 迁移、升级、Vue2→Vue3 | 行为等价的 Vue3 项目 |
+| **Harness** | 归因回流、记录教训 | LEARNINGS.md 经验条目 |
+
+详细说明参见 [USAGE.md](./USAGE.md)。
+
+---
+
+## 设计决策
+
+| 决策 | 理由 |
+|------|------|
+| 纯 Markdown Skill | 零平台依赖，一份内容多平台复用 |
+| npm 分发 | semver + 一致性 + CI 友好 |
+| 路径映射而非配置文件 | 新增平台只改一行代码 |
+| LEARNINGS.md 保留策略 | sync 不丢失用户积累的经验 |
+| ESM + Node >= 18 | 使用原生 fs recursive、top-level await |
+| 脚本 chmod 自动化 | 用户无需手动 `chmod +x` |
+| marker 文件防重复 | init 幂等，sync 精准定位 |
+
+---
+
+## 相关文档
+
+- [USAGE.md](./USAGE.md) — 完整使用说明（功能详解、使用案例、内部机制、设计亮点、对比分析）
+
+---
+
+## License
+
+MIT

package/bin/lcap-frontend-library.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/index.js';
+main();

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,27 @@
+import { Command } from 'commander';
+import { init } from './init.js';
+import { sync } from './sync.js';
+export async function main() {
+    const program = new Command();
+    program
+        .name('lcap-frontend-library')
+        .description('LCAP 前端扩展组件库 AI Skill 分发器')
+        .version('0.1.0');
+    program
+        .command('init')
+        .description('首次安装：选择工具 → 投放 skill')
+        .option('--tools <tools>', '指定工具（逗号分隔）：claude,cursor,codex')
+        .option('--global', '安装到全局目录（~/.claude/skills/ 等）')
+        .option('--all', '投放到所有支持的工具')
+        .action(async (options) => {
+        await init(process.cwd(), options);
+    });
+    program
+        .command('sync')
+        .description('同步：将包内最新 skill 投放到已记录的工具目录')
+        .option('--tools <tools>', '指定工具（逗号分隔），默认使用 init 时的选择')
+        .action((options) => {
+        sync(process.cwd(), options);
+    });
+    await program.parseAsync();
+}

package/dist/init.d.ts

@@ -0,0 +1,6 @@
+export interface InitOptions {
+    tools?: string;
+    all?: boolean;
+    global?: boolean;
+}
+export declare function init(projectDir: string, options: InitOptions): Promise<void>;

package/dist/init.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { select, checkbox } from '@inquirer/prompts';
+import { TOOL_PATHS, GLOBAL_TOOL_PATHS, SKILL_NAME, getSkillSourceDir, getPackageVersion, readMarker, writeMarker, copyDirRecursive, chmodScripts, } from './utils.js';
+export async function init(projectDir, options) {
+    // Determine scope from flags
+    let scope = options.global ? 'global' : 'project';
+    // Check if already installed for this scope
+    const marker = readMarker(projectDir, scope);
+    if (marker) {
+        console.log(`⚠ ${SKILL_NAME} 已安装 (v${marker.version})，范围: ${marker.scope}，工具: ${marker.tools.join(', ')}`);
+        console.log(`  如需同步最新版本，请使用: npx ${SKILL_NAME} sync`);
+        return;
+    }
+    let tools;
+    if (options.all) {
+        // --all: select all tools for the determined scope
+        tools = scope === 'global' ? Object.keys(GLOBAL_TOOL_PATHS) : Object.keys(TOOL_PATHS);
+    }
+    else if (options.tools) {
+        // --tools provided: direct execution
+        const pathMap = scope === 'global' ? GLOBAL_TOOL_PATHS : TOOL_PATHS;
+        tools = options.tools.split(',').map(t => t.trim()).filter(t => t in pathMap);
+        if (tools.length === 0) {
+            console.error(`错误：无效的工具名。可选: ${Object.keys(pathMap).join(', ')}`);
+            process.exit(1);
+        }
+    }
+    else if (process.stdout.isTTY) {
+        // Interactive mode
+        scope = await select({
+            message: '安装范围',
+            choices: [
+                { value: 'project', name: '当前项目（推荐）' },
+                { value: 'global', name: '全局（所有项目共享）' },
+            ],
+        });
+        const availableTools = scope === 'global'
+            ? Object.keys(GLOBAL_TOOL_PATHS)
+            : Object.keys(TOOL_PATHS);
+        tools = await checkbox({
+            message: '选择要安装的 AI 工具（空格选择，回车确认）',
+            choices: availableTools.map(t => ({ value: t, name: t, checked: true })),
+        });
+        if (tools.length === 0) {
+            console.error('错误：至少选择一个工具');
+            process.exit(1);
+        }
+    }
+    else {
+        // Non-TTY fallback: project-level, all tools
+        tools = Object.keys(TOOL_PATHS);
+        console.log(`未检测到终端交互，将为所有工具创建: ${tools.join(', ')}`);
+    }
+    const skillSrc = getSkillSourceDir();
+    if (!fs.existsSync(skillSrc)) {
+        console.error(`错误：skill 源目录不存在: ${skillSrc}`);
+        process.exit(1);
+    }
+    const version = getPackageVersion();
+    // Deploy to each tool
+    for (const tool of tools) {
+        const targetDir = scope === 'global'
+            ? GLOBAL_TOOL_PATHS[tool]
+            : path.join(projectDir, TOOL_PATHS[tool]);
+        console.log(`  → ${scope === 'global' ? GLOBAL_TOOL_PATHS[tool] : TOOL_PATHS[tool]}/`);
+        copyDirRecursive(skillSrc, targetDir);
+        chmodScripts(targetDir);
+    }
+    // Write marker
+    writeMarker(projectDir, {
+        version,
+        tools,
+        scope,
+        installedAt: new Date().toISOString(),
+    });
+    console.log(`\n✓ ${SKILL_NAME} v${version} 已安装（${scope === 'global' ? '全局' : '项目级'}）`);
+    console.log(`\n使用方式：在 AI 工具中输入 /${SKILL_NAME}`);
+}

package/dist/sync.d.ts

@@ -0,0 +1,4 @@
+export interface SyncOptions {
+    tools?: string;
+}
+export declare function sync(projectDir: string, options: SyncOptions): void;

package/dist/sync.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TOOL_PATHS, GLOBAL_TOOL_PATHS, SKILL_NAME, getSkillSourceDir, getPackageVersion, readMarker, writeMarker, copyDirRecursive, chmodScripts, rmDirRecursive, } from './utils.js';
+export function sync(projectDir, options) {
+    const marker = readMarker(projectDir);
+    if (!marker) {
+        console.error(`错误：未找到 .lcap-skill.json，请先执行: npx ${SKILL_NAME} init`);
+        process.exit(1);
+    }
+    const scope = marker.scope || 'project';
+    const pathMap = scope === 'global' ? GLOBAL_TOOL_PATHS : TOOL_PATHS;
+    // Determine target tools
+    let tools;
+    if (options.tools) {
+        tools = options.tools.split(',').map(t => t.trim()).filter(t => t in pathMap);
+        if (tools.length === 0) {
+            console.error(`错误：无效的工具名。可选: ${Object.keys(pathMap).join(', ')}`);
+            process.exit(1);
+        }
+    }
+    else {
+        tools = marker.tools;
+    }
+    const skillSrc = getSkillSourceDir();
+    if (!fs.existsSync(skillSrc)) {
+        console.error(`错误：skill 源目录不存在: ${skillSrc}`);
+        process.exit(1);
+    }
+    const oldVersion = marker.version;
+    const newVersion = getPackageVersion();
+    for (const tool of tools) {
+        const targetDir = scope === 'global'
+            ? GLOBAL_TOOL_PATHS[tool]
+            : path.join(projectDir, TOOL_PATHS[tool]);
+        // Backup LEARNINGS.md if it exists and has user content
+        const learningsPath = path.join(targetDir, 'LEARNINGS.md');
+        let learningsBackup = null;
+        if (fs.existsSync(learningsPath)) {
+            const content = fs.readFileSync(learningsPath, 'utf8');
+            if (content.includes('### LEARN-')) {
+                learningsBackup = content;
+            }
+        }
+        // Remove old skill directory
+        rmDirRecursive(targetDir);
+        // Copy fresh skill
+        const displayPath = scope === 'global' ? GLOBAL_TOOL_PATHS[tool] : TOOL_PATHS[tool];
+        console.log(`  → ${displayPath}/`);
+        copyDirRecursive(skillSrc, targetDir);
+        chmodScripts(targetDir);
+        // Restore LEARNINGS.md
+        if (learningsBackup) {
+            fs.writeFileSync(learningsPath, learningsBackup);
+            console.log(`    ↳ LEARNINGS.md 已保留（含用户记录）`);
+        }
+    }
+    // Update marker
+    writeMarker(projectDir, {
+        version: newVersion,
+        tools,
+        scope,
+        installedAt: new Date().toISOString(),
+    });
+    if (oldVersion !== newVersion) {
+        console.log(`\n✓ synced v${oldVersion} → v${newVersion}`);
+    }
+    else {
+        console.log(`\n✓ synced (v${newVersion}，内容已同步)`);
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+export declare const SKILL_NAME = "lcap-frontend-library";
+export declare const TOOL_PATHS: Record<string, string>;
+export declare const GLOBAL_TOOL_PATHS: Record<string, string>;
+export declare const MARKER_FILE = ".lcap-skill.json";
+export interface Marker {
+    version: string;
+    tools: string[];
+    scope: 'global' | 'project';
+    installedAt: string;
+}
+export declare function getSkillSourceDir(): string;
+export declare function getPackageVersion(): string;
+export declare function getMarkerPath(projectDir: string, scope: 'global' | 'project'): string;
+export declare function readMarker(projectDir: string, scope?: 'global' | 'project'): Marker | null;
+export declare function writeMarker(projectDir: string, marker: Marker): void;
+export declare function detectTools(projectDir: string): string[];
+export declare function copyDirRecursive(src: string, dest: string): void;
+export declare function chmodScripts(skillDir: string): void;
+export declare function rmDirRecursive(dir: string): void;

package/dist/utils.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const SKILL_NAME = 'lcap-frontend-library';
+export const TOOL_PATHS = {
+    claude: `.claude/skills/${SKILL_NAME}`,
+    cursor: `.cursor/skills/${SKILL_NAME}`,
+    codex: `.codex/skills/${SKILL_NAME}`,
+};
+export const GLOBAL_TOOL_PATHS = {
+    claude: path.join(os.homedir(), '.claude', 'skills', SKILL_NAME),
+    cursor: path.join(os.homedir(), '.cursor', 'skills', SKILL_NAME),
+    codex: path.join(os.homedir(), '.codex', 'skills', SKILL_NAME),
+};
+export const MARKER_FILE = '.lcap-skill.json';
+export function getSkillSourceDir() {
+    return path.resolve(__dirname, '..', 'packages', 'lcap-frontend-library');
+}
+export function getPackageVersion() {
+    const pkgPath = path.resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+}
+export function getMarkerPath(projectDir, scope) {
+    if (scope === 'global')
+        return path.join(os.homedir(), MARKER_FILE);
+    return path.join(projectDir, MARKER_FILE);
+}
+export function readMarker(projectDir, scope) {
+    // If scope is specified, only check that scope
+    if (scope) {
+        const markerPath = getMarkerPath(projectDir, scope);
+        if (!fs.existsSync(markerPath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    // Try project first, then global
+    for (const s of ['project', 'global']) {
+        const markerPath = getMarkerPath(projectDir, s);
+        if (fs.existsSync(markerPath)) {
+            try {
+                return JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+export function writeMarker(projectDir, marker) {
+    const markerPath = getMarkerPath(projectDir, marker.scope);
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2) + '\n');
+}
+export function detectTools(projectDir) {
+    const detected = [];
+    for (const tool of Object.keys(TOOL_PATHS)) {
+        const toolRoot = path.join(projectDir, `.${tool}`);
+        if (fs.existsSync(toolRoot)) {
+            detected.push(tool);
+        }
+    }
+    return detected;
+}
+export function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export function chmodScripts(skillDir) {
+    const bashDir = path.join(skillDir, 'scripts', 'bash');
+    if (!fs.existsSync(bashDir))
+        return;
+    const files = fs.readdirSync(bashDir);
+    for (const file of files) {
+        if (file.endsWith('.sh')) {
+            fs.chmodSync(path.join(bashDir, file), 0o755);
+        }
+    }
+}
+export function rmDirRecursive(dir) {
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "lcap-frontend-library",
+  "version": "0.0.1",
+  "description": "LCAP 前端扩展组件库 AI Skill（Claude Code / Cursor / Codex）",
+  "type": "module",
+  "bin": {
+    "lcap-frontend-library": "./bin/lcap-frontend-library.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "packages/lcap-frontend-library"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test tests/",
+    "publish:dry-run": "npm pack --dry-run",
+    "publish:npm": "npm publish"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/packages/lcap-frontend-library/LEARNINGS.md

@@ -0,0 +1,11 @@
+# LEARNINGS
+
+> 轻量经验库：用户主动归因回流写入；generate / migrate 下次执行时只读引用。
+> **写入**：仅用户说「归因回流」等触发 harness，不自动写入。
+> **读取**：作为先验知识（plan）、checklist（self-check/check）、流程约束（implement/green）。
+> 区别于 `workflows/migrate/knowledge-base.md` §pitfalls（权威静态规则）与 `workflow-guardrails.md`（跨流程护栏）。
+> 每条格式：**[场景关键词]**：什么情况 + 什么坑/正确做法。
+
+---
+
+(暂无记录，随使用积累)