lcap-frontend-library

LCAP 前端扩展组件库 AI Skill 分发 CLI —— 将领域知识注入 AI 编码助手

这是什么

本仓库包含两部分：

| 部分 | 职责 | |------|------| | CLI（bin/ + src/） | 将 Skill 内容复制到 Claude / Cursor / Codex 的 skill 目录 | | Skill 内容（packages/lcap-frontend-library/） | 纯 Markdown 指令集，定义 create / migrate / harness 工作流 |

核心理念：AI Skill as npm package —— init 部署、sync 升级；同一份 Markdown 通过路径映射适配多平台，无平台专有 API。

快速开始

# 部署 Skill
npx lcap-frontend-library init

# 同步最新版本
npx lcap-frontend-library sync

验证：

ls .cursor/skills/lcap-frontend-library/SKILL.md
cat .lcap-skill.json

在 AI 工具中输入自然语言即可触发工作流，例如「生成一个二维码组件」「把这个库从 Vue2 迁移到 Vue3」。

完整用法见 USAGE.md。

CLI 命令

init — 首次部署

npx lcap-frontend-library init [--tools claude,cursor] [--global] [--all]

| 选项 | 说明 | |------|------| | --tools <list> | 指定工具（逗号分隔） | | --global | 部署到 ~/.{tool}/skills/ | | --all | 部署到全部支持的工具 |

• TTY 环境：交互选择范围与工具
• 非 TTY（CI）：默认全部工具 + 项目级
• 已安装：提示使用 sync

sync — 更新 Skill

npx lcap-frontend-library sync [--tools claude,cursor]

1. 读取 .lcap-skill.json 确定目标
2. 删除旧目录 → 复制 packages/lcap-frontend-library/ 最新内容
3. 保留含 ### LEARN- 标记的 LEARNINGS.md
4. 更新 marker 版本号

仓库结构

lcap-frontend-library/                    # npm 包根目录
├── bin/lcap-frontend-library.mjs         # CLI 入口
├── src/                                  # CLI 源码（编译 → dist/）
│   ├── index.ts                          # init / sync 命令注册
│   ├── init.ts                           # 部署逻辑
│   ├── sync.ts                           # 同步逻辑
│   └── utils.ts                          # 路径映射、文件复制、marker
├── dist/                                 # tsc 编译产物（运行时加载）
├── packages/lcap-frontend-library/       # ★ Skill 内容（随 npm 包分发）
├── tests/                                # CLI 单元测试
├── USAGE.md                              # 用户使用说明
├── docs/                                 # 设计文档
└── package.json

CLI 通过 getSkillSourceDir() 读取 packages/lcap-frontend-library/，复制到用户项目的 AI 工具目录：

.cursor/skills/lcap-frontend-library/     # 项目级示例
~/.cursor/skills/lcap-frontend-library/   # 全局级

Skill 内容结构

Skill 采用 路由 → 流程 → 命令 三层编排，所有文件位于 packages/lcap-frontend-library/：

packages/lcap-frontend-library/
├── SKILL.md                          # L1 路由：意图识别 → flow 指针
├── LEARNINGS.md                      # 经验库（harness 写入，workflow 只读）
│
├── workflows/                        # L2 流程：阶段顺序与成功标准
│   ├── create/flow.md                #   7 阶段 speckit（新建/追加资产）
│   ├── migrate/flow.md               #   7 命令 TDD（Vue2→Vue3）
│   │   └── knowledge-base.md         #   迁移领域知识（§section-id 索引）
│   ├── harness/flow.md               #   归因回流 → LEARNINGS.md
│
├── commands/                         # L3 命令：各阶段详细执行指令（13 个）
│   ├── speckit.create.md             #   INIT
│   ├── speckit.specify.md            #   SPECIFY
│   ├── speckit.plan.md               #   PLAN
│   ├── speckit.tasks.md              #   TASKS
│   ├── speckit.implement.md          #   IMPLEMENT
│   ├── speckit.self-check.md         #   SELF-CHECK
│   ├── migrate.scan.md               #   SCAN（库级，1 次）
│   ├── migrate.spec.md               #   SPEC
│   ├── migrate.plan.md               #   PLAN（⛔ 用户审批）
│   ├── migrate.tasks.md              #   TASKS
│   ├── migrate.red.md                #   RED
│   ├── migrate.green.md              #   GREEN
│   └── migrate.check.md              #   CHECK
│
├── references/                       # 领域知识（plan/implement 阶段引用）
│   ├── lcap-extension-component/     #   组件规范（api、ide、platform…）
│   ├── frontend-design/              #   前端观感
│   └── nasl-logic-authoring/         #   @NaslLogic 逻辑函数
│
├── templates/                        # spec / plan / tasks / migration 输出模板
└── scripts/                          # 脚手架（bash + node）
    ├── bash/                         #   建库、建组件/逻辑骨架、create-spec
    └── node/                         #   setup-extension-project.mjs

工作流一览

| 路由 | flow | 阶段 | 命令前缀 | 典型触发 | |------|------|------|----------|----------| | create | workflows/create/flow.md | INIT → … → BUILD-VERIFY（7 步） | speckit.* | 生成、新建、追加组件/逻辑 | | migrate | workflows/migrate/flow.md | SCAN → … → CHECK（7 命令） | migrate.* | Vue2 转 Vue3、迁移升级 | | harness | workflows/harness/flow.md | 回顾 → 精炼 → 写入 | — | 归因回流、记录教训 |

Harness 与 create/migrate 并列，不是 migrate 的收尾。LEARNINGS.md 由 harness 写入，create 与 migrate 在 plan / implement / check 阶段对称只读消费。

create 在 INIT 阶段若检测到目标资产已存在，直接报错终止（不支持增量修改已有资产）。

开发与发布

git clone <repo-url> && cd npm/lcap-frontend-library
npm install
npm test          # build + 路径回归测试

修改 Skill 内容：直接编辑 packages/lcap-frontend-library/，无需额外同步脚本。

本地验证 CLI：

node bin/lcap-frontend-library.mjs init --tools cursor
# 或 npm link && lcap-frontend-library init

发布：

npm version patch
npm run publish:npm     # 等价于 npm publish（prepublishOnly 自动 build）
npm run publish:dry-run # 预览 tarball 内容

用户侧通过 npx lcap-frontend-library sync 获取更新。

多平台适配

路径映射定义于 src/utils.ts：

| 工具 | 项目级 | 全局级 | |------|--------|--------| | 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/ |

新增平台：在 TOOL_PATHS 与 GLOBAL_TOOL_PATHS 各加一行，init / sync 自动适配。

设计决策

| 决策 | 理由 | |------|------| | Skill 内聚于 npm 包 | 删除外部 sync-skill，版本与内容同源 | | 纯 Markdown | 零平台 API 依赖，一份内容多工具复用 | | 路径映射 | 新增平台只改 utils.ts 两行 | | .lcap-skill.json marker | init 幂等、sync 精准定位 | | sync 保留 LEARNINGS | 不丢失用户积累的经验 | | ESM + Node ≥ 18 | 原生 fs recursive、现代模块 |

相关文档

• USAGE.md — 路由分发、流程编排、使用案例、内部机制

License

MIT