moluoxixi-ai-rules 0.1.0

package/dist/constants/skills.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 安装前置命令必须以结构化参数声明，避免把配置内容拼进 shell 字符串。
+ */
+export interface SetupCommand {
+    command: string;
+    args?: string[];
+}
+/**
+ * 单个 skill 的详细配置（适用于需要重命名或前置安装命令的场景）
+ */
+export interface SkillConfig {
+    /** 仓库内源目录名 */
+    name: string;
+    /** 安装后目录名，默认与 name 相同 */
+    output?: string;
+    /**
+     * 该 skill 的安装前置命令。
+     * 在 skill 链接建立后执行，例如安装对应的全局 CLI 工具。
+     * 例如：[{ command: 'some-cli-installer', args: ['--global'] }]
+     * 命令按顺序执行，任一失败均会抛出错误并中断整体流程。
+     */
+    setup?: SetupCommand[];
+}
+/**
+ * 技能定义：
+ * - 字符串：简写形式，源目录名 === 安装后目录名，无 setup
+ * - SkillConfig：对象形式，支持重命名和 per-skill setup 命令
+ */
+export type SkillDef = string | SkillConfig;
+/**
+ * 单个供应商仓库内的一条安装投影规则。
+ * namespace 用于递归扫描目录中的叶子 skills；skills 用于按 skill 精确投影。
+ * 两者安装到 vendor/skills 时都只保留叶子 skill 名称，不继承源目录层级。
+ */
+export type VendorProjection = {
+    kind: 'namespace';
+    /** 仓库内要递归扫描的目录 */
+    sourceDir: string;
+    /** 清单中的占位名；实际 vendor 目录由叶子 skill 名称决定 */
+    output: string;
+    /** namespace 级安装前置命令 */
+    setup?: SetupCommand[];
+} | {
+    kind: 'skills';
+    /** 仓库内技能所在的基准目录 */
+    sourceBaseDir: string;
+    /** 需要精确安装的技能列表 */
+    skills: SkillDef[];
+};
+/**
+ * 代表一个外部供应商的技能仓库
+ */
+export interface VendorRepo {
+    /** 供应商名称，也是克隆到本地后的目录名 */
+    name: string;
+    /** 是否为官方仓库 */
+    official: boolean;
+    /** Git 仓库地址 */
+    source: string;
+    /** 从该仓库投影到 vendor/skills 的安装规则列表 */
+    projections: VendorProjection[];
+}
+/**
+ * 技能节点：可以是一个具体的 VendorRepo 实例，也可以是一个包含多个节点的分类对象。
+ * 这种递归结构允许在数组中直接混合使用"扁平技能"和"嵌套分类"。
+ */
+export type VendorNode = VendorRepo | {
+    [category: string]: VendorNode[];
+};
+/**
+ * 供应商配置：必须是一个 VendorNode 数组。
+ * 这种结构提供了极大的灵活性：
+ * - 如果直接放入 VendorRepo，安装时会扁平化到顶级。
+ * - 如果放入 { "category": [...] }，category 只作为配置分组，不进入 vendor/skills 路径。
+ */
+export type VendorsConfig = VendorNode[];
+/**
+ * @see https://github.com/vercel/next.js.git next.js官方仓库
+ * @see https://github.com/vercel/next.js/tree/canary/.claude-plugin/plugins/cache-components/skills next.js官方用于claude的skills
+ * @see https://github.com/facebook/react.git react官方仓库
+ * @see https://github.com/antfu/skills.git antfu的技能仓库，收集了很多前端技能
+ * @see https://github.com/facebook/react/tree/main/.claude/skills react官方用于claude的skills
+ * @see https://github.com/vercel-labs/agent-skills.git Vercel官方面向AI代理的React/React Native技能仓库
+ * @see https://github.com/vercel-labs/web-interface-guidelines.git Vercel官方Web界面规范
+ * @see https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/awesome_agent_skills awesome-agent-skills仓库，收集了很多技能
+ * @see https://github.com/anthropics/skills.git anthropic（claude）官方技能仓库
+ * @see https://github.com/google-gemini/gemini-cli.git gemini官方技能仓库
+ * @see https://github.com/openai/skills.git openai官方技能仓库
+ * @see https://github.com/obra/superpowers.git superpowers官方技能仓库
+ */
+export declare const vendors: VendorsConfig;

package/dist/constants/skills.js

@@ -0,0 +1,156 @@
+/**
+ * @see https://github.com/vercel/next.js.git next.js官方仓库
+ * @see https://github.com/vercel/next.js/tree/canary/.claude-plugin/plugins/cache-components/skills next.js官方用于claude的skills
+ * @see https://github.com/facebook/react.git react官方仓库
+ * @see https://github.com/antfu/skills.git antfu的技能仓库，收集了很多前端技能
+ * @see https://github.com/facebook/react/tree/main/.claude/skills react官方用于claude的skills
+ * @see https://github.com/vercel-labs/agent-skills.git Vercel官方面向AI代理的React/React Native技能仓库
+ * @see https://github.com/vercel-labs/web-interface-guidelines.git Vercel官方Web界面规范
+ * @see https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/awesome_agent_skills awesome-agent-skills仓库，收集了很多技能
+ * @see https://github.com/anthropics/skills.git anthropic（claude）官方技能仓库
+ * @see https://github.com/google-gemini/gemini-cli.git gemini官方技能仓库
+ * @see https://github.com/openai/skills.git openai官方技能仓库
+ * @see https://github.com/obra/superpowers.git superpowers官方技能仓库
+ */
+export const vendors = [
+    {
+        name: 'gemini',
+        official: true,
+        source: 'https://github.com/google-gemini/gemini-cli.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: '.gemini/skills',
+                skills: ['code-reviewer', 'pr-creator'],
+            },
+        ],
+    },
+    {
+        name: 'vercelLabs',
+        official: true,
+        source: 'https://github.com/vercel-labs/skills.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                skills: ['find-skills'],
+            },
+        ],
+    },
+    {
+        name: 'vercelAgentSkills',
+        official: true,
+        source: 'https://github.com/vercel-labs/agent-skills.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                skills: [
+                    {
+                        name: 'react-best-practices',
+                        output: 'vercel-react-best-practices',
+                    },
+                    {
+                        name: 'react-native-skills',
+                        output: 'vercel-react-native-skills',
+                    },
+                    'web-design-guidelines',
+                ],
+            },
+        ],
+    },
+    {
+        name: 'anthropic',
+        official: true,
+        source: 'https://github.com/anthropics/skills.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                skills: [
+                    'frontend-design',
+                ],
+            },
+        ],
+    },
+    {
+        name: 'antfu',
+        official: true,
+        source: 'https://github.com/antfu/skills.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                skills: [
+                    // 只保留具体技术栈技能，避免顶层个人偏好规则抢占代码库第一方 workflow。
+                    'pnpm',
+                    'slidev',
+                    'tsdown',
+                    'turborepo',
+                    'vitest',
+                    'nuxt',
+                    'pinia',
+                    'unocss',
+                    'vite',
+                    'vitepress',
+                    'vue',
+                    'vue-best-practices',
+                    'vue-router-best-practices',
+                    'vue-testing-best-practices',
+                    'vueuse-functions',
+                ],
+            },
+        ],
+    },
+    {
+        name: 'openai',
+        official: true,
+        source: 'https://github.com/openai/skills.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills/.curated',
+                skills: ['playwright'],
+            },
+        ],
+    },
+    {
+        name: 'superpowers',
+        official: true,
+        source: 'https://github.com/obra/superpowers.git',
+        projections: [
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                // 投影代码库常用工作流子集；TDD、子代理执行与分支收尾仍由第一方 workflow 按风险显式触发。
+                skills: [
+                    'systematic-debugging',
+                    'verification-before-completion',
+                    'receiving-code-review',
+                    'writing-skills',
+                    'using-git-worktrees',
+                    'writing-plans',
+                ],
+            },
+        ],
+    },
+    {
+        name: 'moluoxixi',
+        official: true,
+        source: 'https://github.com/moluoxixi/AIRules.git',
+        projections: [
+            {
+                kind: 'namespace',
+                sourceDir: 'skills/workflow',
+                output: 'workflow',
+            },
+            {
+                kind: 'skills',
+                sourceBaseDir: 'skills',
+                skills: [
+                    'skill-validation-standard',
+                ],
+            },
+        ],
+    },
+];

package/dist/scripts/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import kleur from 'kleur';
+import { addLocalSkill, getDefaultMoluoHome, syncToHosts, verifyHosts, } from './lib/tool.js';
+function findPackageRoot(fromFileUrl) {
+    let currentDir = path.dirname(fileURLToPath(fromFileUrl));
+    while (!existsSync(path.join(currentDir, 'package.json'))) {
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            throw new Error(`Unable to locate package.json from ${fromFileUrl}`);
+        }
+        currentDir = parentDir;
+    }
+    return currentDir;
+}
+const PACKAGE_ROOT = findPackageRoot(import.meta.url);
+function printHelp() {
+    console.log(`Usage:
+  airules sync [--host <name|all>] [--home <dir>] [--user-home <dir>] [--skip-vendors] [--no-verify]
+  airules add <skill-dir> [--name <skill-name>] [--host <name|all>] [--home <dir>] [--user-home <dir>] [--overwrite] [--skip-sync] [--sync-vendors]
+  airules verify [--host <name|all>] [--home <dir>] [--user-home <dir>]
+
+Commands:
+  sync      同步内置、用户自定义和第三方 skills 到宿主
+  add       添加包含 SKILL.md 的本地 skill 目录，并默认同步到宿主
+  verify    校验宿主 skills 链接完整性
+`);
+}
+function parseCommandArgs(args) {
+    return parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            'help': { type: 'boolean', short: 'h' },
+            'home': { type: 'string' },
+            'host': { type: 'string' },
+            'name': { type: 'string' },
+            'overwrite': { type: 'boolean' },
+            'no-verify': { type: 'boolean' },
+            'repo-root': { type: 'string' },
+            'skip-sync': { type: 'boolean' },
+            'skip-vendors': { type: 'boolean' },
+            'sync-vendors': { type: 'boolean' },
+            'user-home': { type: 'string' },
+        },
+        strict: true,
+    });
+}
+function commonOptions(values) {
+    return {
+        home: String(values.home ?? getDefaultMoluoHome()),
+        host: String(values.host ?? 'all'),
+        repoRoot: String(values['repo-root'] ?? PACKAGE_ROOT),
+        userHome: values['user-home'] === undefined ? undefined : String(values['user-home']),
+    };
+}
+async function runSync(args) {
+    const { values } = parseCommandArgs(args);
+    if (values.help === true) {
+        printHelp();
+        return;
+    }
+    const options = commonOptions(values);
+    const result = await syncToHosts({
+        ...options,
+        skipVendors: values['skip-vendors'] === true,
+        verify: values['no-verify'] !== true,
+    });
+    console.log(kleur.green(`[sync] 完成: ${result.projectedHosts.join(', ') || '无宿主投影'}`));
+    console.log(`[home] ${result.moluoHome}`);
+    if (result.skippedHosts.length > 0) {
+        console.log(`[skip] 宿主目录不存在: ${result.skippedHosts.join(', ')}`);
+    }
+}
+async function runAdd(args) {
+    const { positionals, values } = parseCommandArgs(args);
+    if (values.help === true) {
+        printHelp();
+        return;
+    }
+    const options = commonOptions(values);
+    const sourceDir = positionals[0];
+    if (sourceDir === undefined) {
+        throw new Error('Missing <skill-dir> for add command');
+    }
+    const added = addLocalSkill({
+        sourceDir,
+        moluoHome: options.home,
+        name: values.name === undefined ? undefined : String(values.name),
+        overwrite: values.overwrite === true,
+    });
+    console.log(kleur.green(`[add] ${added.skillName} -> ${added.targetDir}`));
+    if (values['skip-sync'] === true) {
+        return;
+    }
+    const result = await syncToHosts({
+        ...options,
+        skipVendors: values['sync-vendors'] !== true,
+        verify: values['no-verify'] !== true,
+    });
+    console.log(kleur.green(`[sync] 完成: ${result.projectedHosts.join(', ') || '无宿主投影'}`));
+    if (result.skippedHosts.length > 0) {
+        console.log(`[skip] 宿主目录不存在: ${result.skippedHosts.join(', ')}`);
+    }
+}
+async function runVerify(args) {
+    const { values } = parseCommandArgs(args);
+    if (values.help === true) {
+        printHelp();
+        return;
+    }
+    const options = commonOptions(values);
+    const targets = await verifyHosts({
+        home: options.home,
+        host: options.host,
+    });
+    console.log(kleur.green(`[verify] 通过: ${targets.join(', ')}`));
+}
+async function main() {
+    const [command, ...commandArgs] = process.argv.slice(2);
+    if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+        printHelp();
+        return;
+    }
+    if (command === 'sync') {
+        await runSync(commandArgs);
+        return;
+    }
+    if (command === 'add') {
+        await runAdd(commandArgs);
+        return;
+    }
+    if (command === 'verify') {
+        await runVerify(commandArgs);
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+main().catch((error) => {
+    console.error(kleur.red(String(error)));
+    process.exit(1);
+});

package/dist/scripts/host-setup.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env npx tsx
+export {};

package/dist/scripts/host-setup.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env npx tsx
+import os from 'node:os';
+import path from 'node:path';
+import kleur from 'kleur';
+import { ALL_HOST_IDS } from '../constants/hosts.js';
+import { ensureGlobalSkillLink, ensureInstallRoot, getDefaultInstallPaths, linkHostBaseline, projectHostById, rebuildVendorSkillLinks, runSkillSetupCommands, syncFirstPartySkillsToVendor, syncFirstPartyToHome, } from './lib/install.js';
+import { ensureVendorRepo } from './lib/vendor-sync.js';
+import { loadVendorManifest } from './lib/vendors.js';
+import { verifyHost } from './lib/verify.js';
+function printHelp() {
+    const hostsLine = ALL_HOST_IDS.join('\n  ');
+    console.log(`Usage: npx tsx scripts/host-setup.ts --host <name|all> [--mode <install|upgrade>] [--home <dir>] [--user-home <dir>] [--skip-vendors]
+
+Hosts:
+  all (安装到所有支持的代理)
+  ${hostsLine}
+`);
+}
+function parseArgs(argv) {
+    const args = {
+        host: '',
+        mode: 'install', // 默认安装
+        home: path.join(os.homedir(), '.moluoxixi'),
+        skipVendors: false,
+        help: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help') {
+            args.help = true;
+        }
+        else if (arg === '--host') {
+            args.host = argv[index + 1];
+            index += 1;
+        }
+        else if (arg === '--mode') {
+            args.mode = argv[index + 1];
+            index += 1;
+        }
+        else if (arg === '--home') {
+            args.home = argv[index + 1];
+            index += 1;
+        }
+        else if (arg === '--user-home') {
+            args.userHome = argv[index + 1];
+            index += 1;
+        }
+        else if (arg === '--skip-vendors') {
+            args.skipVendors = true;
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return args;
+}
+function assertRequiredArgs(args) {
+    if (!args.host) {
+        throw new Error('Missing required --host argument');
+    }
+    if (!args.mode || !['install', 'upgrade'].includes(args.mode)) {
+        throw new Error('Missing or invalid --mode argument (expected install or upgrade)');
+    }
+}
+async function syncVendorsIfNeeded(homeDir, repoRoot, skipVendors) {
+    if (skipVendors) {
+        return;
+    }
+    const manifest = await loadVendorManifest(path.join(repoRoot, 'constants', 'skills.js'));
+    for (const vendor of Object.values(manifest.vendors ?? {})) {
+        ensureVendorRepo(homeDir, vendor);
+    }
+    // 执行各 skill 的安装前置命令
+    runSkillSetupCommands(manifest);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        return;
+    }
+    assertRequiredArgs(args);
+    const repoRoot = process.cwd();
+    const userHome = path.resolve(args.userHome ?? os.homedir());
+    const paths = getDefaultInstallPaths(userHome);
+    paths.moluoHome = path.resolve(args.home);
+    paths.repoRoot = repoRoot;
+    ensureInstallRoot(paths);
+    ensureGlobalSkillLink(paths);
+    syncFirstPartyToHome(repoRoot, paths.moluoHome);
+    await syncVendorsIfNeeded(paths.moluoHome, repoRoot, args.skipVendors);
+    await rebuildVendorSkillLinks({
+        homeDir: paths.moluoHome,
+        manifestPath: path.join(repoRoot, 'constants', 'skills.js'),
+    });
+    syncFirstPartySkillsToVendor(repoRoot, paths.moluoHome);
+    syncFirstPartySkillsToVendor(paths.moluoHome, paths.moluoHome);
+    const targets = args.host === 'all' ? ALL_HOST_IDS : [args.host];
+    const failedHosts = [];
+    const installErrors = [];
+    for (const host of targets) {
+        try {
+            const { success } = projectHostById(host, userHome, paths.moluoHome);
+            if (success) {
+                const baselineTarget = linkHostBaseline({
+                    moluoHome: paths.moluoHome,
+                    host,
+                    userHome,
+                });
+                console.log(`[host] ${host} - 配置完成`);
+                if (baselineTarget) {
+                    console.log(`[baseline] ${baselineTarget}`);
+                }
+                // 自动执行校验逻辑
+                const verified = await verifyHost(host, paths.moluoHome, userHome);
+                if (!verified) {
+                    failedHosts.push(host);
+                }
+            }
+        }
+        catch (error) {
+            installErrors.push(host);
+            console.error(`[error] ${host} 安装过程中发生异常:`);
+            console.error(String(error));
+        }
+    }
+    const allFailures = [...installErrors, ...failedHosts];
+    const allPassed = allFailures.length === 0;
+    if (allPassed) {
+        console.log(`\n${kleur.green('✅ 所有宿主验证通过，安装/更新流程已完成。')}`);
+    }
+    else {
+        console.error(`\n${kleur.red('❌ 以下宿主未通过验证，请检查上述错误信息：')}`);
+        for (const host of installErrors) {
+            console.error(`  ${kleur.red(`• ${host} — 安装异常`)}`);
+        }
+        for (const host of failedHosts) {
+            console.error(`  ${kleur.red(`• ${host} — 验证失败`)}`);
+        }
+        process.exitCode = 1;
+    }
+    console.log(`[home] ${paths.moluoHome}`);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/scripts/lib/install.d.ts

@@ -0,0 +1,78 @@
+import type { LinkEntry } from './links.js';
+import type { VendorManifest } from './vendors.js';
+/**
+ * 执行各 skill 的安装前置命令（per-skill 精度）。
+ * 遍历 manifest 中所有 vendor 的 links，对具有 setup 字段的 link 执行其命令。
+ * 任一命令失败都会抛出错误，避免安装流程伪装成功。
+ * @param manifest 已解析的 VendorManifest
+ */
+export declare function runSkillSetupCommands(manifest: VendorManifest): void;
+export declare function isSamePath(p1: string, p2: string): boolean;
+export declare function replaceWithSymlink(source: string, target: string, type: 'junction' | 'dir' | 'file'): void;
+export interface InstallPaths {
+    userHome: string;
+    moluoHome: string;
+    repoRoot: string;
+    moluoBaselineFile: string;
+    globalAgentSkillsHome: string;
+    [key: string]: string;
+}
+export declare function getDefaultInstallPaths(userHome?: string): InstallPaths;
+export declare function ensureInstallRoot(paths: InstallPaths): void;
+/**
+ * 确保全局 Agent 技能目录 (~/.agents/skills) 的链接正确。
+ * ~/.agents 是行业标准共享层，始终存在。
+ * 直接从 vendor/skills 映射，无中间层。
+ * 遵循层级自愈同步逻辑。
+ */
+export declare function ensureGlobalSkillLink(paths: InstallPaths): void;
+/**
+ * 同步展平的技能软链接，并清理过时链接。
+ * @param sourceDir 源技能目录
+ * @param targetDir 目标链接目录
+ * @param moluoHome moluoxixi 根目录（用于识别自愈时需要删除的内部链接）
+ */
+export declare function syncFlattenedSkills(sourceDir: string, targetDir: string, moluoHome: string): void;
+/**
+ * 同步第一方（当前仓库内）的 agents 和基线文件到本地 moluoxixi 主目录。
+ * skills 统一走 clone → vendor/skills 流程，不在此处理。
+ *
+ * rules/AGENTS.md 始终复制到 vendor/ 目录下，作为所有宿主基线软链接的统一源。
+ * 即使 repoRoot === moluoHome（仓库本身就是安装目录），也需要执行此步骤，
+ * 因为软链接最终指向的是 vendor/AGENTS.md。
+ */
+export declare function syncFirstPartyToHome(repoRoot: string, moluoHome: string): void;
+/**
+ * 将第一方 skills 源目录投影到 vendor/skills，作为第三方 vendor 后的本地覆盖层。
+ * 该函数只清理曾经指向同一 source skills 根目录的过时链接，不会删除第三方 vendor 技能。
+ */
+export declare function syncFirstPartySkillsToVendor(sourceRoot: string, moluoHome: string): void;
+export declare function rebuildVendorSkillLinks({ homeDir, manifestPath }: {
+    homeDir: string;
+    manifestPath: string;
+}): Promise<LinkEntry[]>;
+/**
+ * 将所有技能投影到宿主软件目录（如 .claude 或 .cursor）。
+ * 链路：vendor/skills → ~/.agents/skills → 宿主/skills
+ * ~/.agents 是行业标准共享层，始终存在（不存在则创建）。
+ */
+export declare function projectSkillsToHost(userHome: string, moluoHome: string, hostSkillsHome: string): void;
+export declare function projectToHost({ userHome, moluoHome, hostHome, hostBaselineFile, customSkillsDirName, }: {
+    userHome: string;
+    moluoHome: string;
+    hostHome: string;
+    hostBaselineFile: string;
+    customSkillsDirName?: string;
+}): void;
+export declare function linkHostBaseline({ moluoHome, host, userHome }: {
+    moluoHome: string;
+    host: string;
+    userHome?: string;
+}): string;
+/**
+ * 将技能和基线投影到指定宿主，并返回是否成功（宿主目录不存在则跳过）。
+ */
+export declare function projectHostById(host: string, userHome: string, moluoHome: string): {
+    success: boolean;
+    hostBaselineFile: string;
+};