momo-ai 1.0.20 → 1.0.21

package/.claude/skills/r2mo-rad-lain/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: r2mo-rad-lain
+description: "R2MO RAD 快速应用开发技能 - 专注于 Momo/LAIN 项目的 CLI 命令开发。支持交互式菜单、参数解析、文件操作等功能。用于快速开发终端工具、交互式界面和命令行应用。"
+version: 2.0.0
+category: 🟢 R2MO RAD (快速应用开发)
+tags:
+  - r2mo
+  - rad
+  - lain
+  - nodejs
+  - cli
+  - momo
+---
+
+# R2MO RAD LAIN 技能
+
+## 概述
+
+本技能用于开发 Momo/LAIN 项目的 CLI 命令。项目采用 CommonJS 规范，使用轻量级原生风格，不依赖 Commander/Yargs 等重型框架。
+
+## 技术栈限制与规范
+
+### 必须遵守
+
+| 项目 | 要求 | 说明 |
+|------|------|------|
+| **模块规范** | CommonJS | 使用 `require`/`module.exports`，禁止使用 ES Module |
+| **Node 版本** | >= 22.x | 项目要求的最低版本 |
+| **参数解析** | 原生/Epic | 使用 `Ec.parseArgument` 或 `process.argv` |
+| **日志输出** | Epic 工具 | 使用 `Ec.info`/`Ec.warn`/`Ec.error`/`Ec.waiting` |
+| **颜色库** | colors | 已全局配置，使用 `.green`/`.blue` 等 |
+| **用户输入** | Ec.ask | 使用项目统一的 readline 封装 |
+
+### 禁止使用
+
+| 项目 | 原因 |
+|------|------|
+| Commander.js | 过重，与项目风格不符 |
+| Yargs | 过重，与项目风格不符 |
+| Inquirer.js | 与项目 readline 冲突 |
+| ES Module (import/export) | 项目使用 CommonJS |
+| TypeScript | 项目使用纯 JavaScript |
+
+### 推荐使用
+
+| 项目 | 场景 |
+|------|------|
+| fs/fs.promises | 文件操作 |
+| path | 路径处理 |
+| os | 系统信息（如 homedir、tmpdir） |
+| child_process | 外部命令执行 |
+| readline | 交互式菜单（仅限本技能脚本） |
+
+## 工作流决策树
+
+### 开发新命令
+1. 阅读本文档 SKILL.md
+2. 创建命令配置 `src/commander/{command}.json`
+3. 创建执行器 `src/executor/execute{Command}.js`
+4. 在 `src/executor/index.js` 中注册
+
+### 需要交互式菜单
+1. **必须阅读**: [`menu-api.md`](menu-api.md) - 完整菜单 API 文档
+2. 使用 `scripts/menu.js` 模块
+3. 菜单完成后再使用 `Ec.ask` 进行确认
+
+### 需要文件操作
+1. **必须阅读**: [`file-utils-api.md`](file-utils-api.md) - 文件工具 API 文档
+2. 使用 `scripts/file-utils.js` 模块
+3. 使用 `scripts/yaml-parser.js` 解析 YAML
+
+## 项目架构
+
+### 目录结构
+```
+src/
+├── commander/          # 命令配置文件 (JSON)
+│   └── {command}.json
+├── executor/           # 命令执行器
+│   ├── index.js        # 执行器导出索引
+│   └── execute{Command}.js
+├── epic/               # 核心工具库
+│   ├── index.js        # 统一导出
+│   ├── momo.fn.log.js  # 日志输出
+│   ├── lain.fn.parse.js # 参数解析
+│   └── ...
+├── _skill/             # 技能配置
+│   └── repositories.json
+└── momo.js             # 主入口
+```
+
+## 命令配置格式
+
+在 `src/commander/` 目录下创建 JSON 配置文件：
+
+```json
+{
+    "executor": "executeMyCommand",
+    "description": "命令描述（CV前缀表示会复制到剪切板）",
+    "command": "mycommand",
+    "options": [
+        {
+            "name": "param",
+            "alias": "p",
+            "description": "参数描述",
+            "type": "string",
+            "default": "默认值"
+        }
+    ]
+}
+```
+
+**字段说明：**
+- `executor`: 对应 `src/executor/` 中的执行器函数名
+- `description`: 命令描述，`（CV）` 前缀表示会复制内容到剪切板
+- `command`: 命令名称
+- `options`: 参数列表
+  - `name`: 参数全名 (--name)
+  - `alias`: 参数别名 (-n)
+  - `type`: 类型 string/number/boolean
+  - `default`: 默认值
+  - `required`: 是否必需
+
+## 执行器开发
+
+### 基础模板
+
+参考 `templates/executor.js.template`：
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const Ec = require('../epic');
+const fsAsync = require('fs').promises;
+
+module.exports = async (options) => {
+    try {
+        // 参数解析
+        const parsed = Ec.parseArgument(options);
+        const paramValue = parsed.param || parsed.p;
+
+        // 业务逻辑
+        Ec.waiting('正在执行...');
+        
+        // 成功退出
+        Ec.info('✅ 执行成功！');
+        process.exit(0);
+    } catch (error) {
+        Ec.error(`❌ 执行失败: ${error.message}`);
+        process.exit(1);
+    }
+};
+```
+
+### 带交互菜单的执行器
+
+参考 `templates/interactive-menu.js.template`。
+
+**关键：使用本技能提供的菜单脚本**
+
+```javascript
+const Ec = require('../epic');
+// 引用技能脚本（需要调整路径或复制到项目中）
+const { selectMultiple } = require('../../skills/r2mo-rad-lain/scripts/menu');
+
+module.exports = async (options) => {
+    const items = [
+        { name: 'item-1', description: '选项一' },
+        { name: 'item-2', description: '选项二' }
+    ];
+
+    // 1. 菜单选择（raw mode）
+    const result = await selectMultiple(items, '选择菜单');
+
+    if (result.items.length === 0) {
+        Ec.waiting('未选择任何项');
+        process.exit(0);
+    }
+
+    // 2. 确认（普通输入模式，菜单完成后才能使用）
+    const answer = await Ec.ask('确认？(y/N): ');
+    if (answer.toLowerCase() !== 'y') {
+        Ec.waiting('已取消');
+        process.exit(0);
+    }
+
+    // 3. 执行操作
+    // ...
+};
+```
+
+## Epic 工具库 API
+
+### 日志输出
+
+```javascript
+Ec.info('绿色信息');      // [Momo AI] 绿色信息
+Ec.waiting('蓝色执行');   // [Momo AI] 蓝色执行
+Ec.warn('黄色警告');      // [Momo AI] 黄色警告
+Ec.error('红色错误');     // [Momo ER] 红色错误
+```
+
+### 参数解析
+
+```javascript
+const parsed = Ec.parseArgument(options);
+// 支持 --name 和 -n 两种形式
+const value = parsed.name || parsed.n;
+```
+
+**注意：** `Ec.parseArgument` 要求参数成对出现。对于可选值参数（如 `-r` 可带可不带值），需要自行解析 `process.argv`。
+
+### 用户输入
+
+```javascript
+const answer = await Ec.ask('请输入: ');
+// 程序退出前关闭
+Ec.askClose();
+```
+
+### 颜色扩展
+
+```javascript
+'文本'.green   // 绿色
+'文本'.blue    // 蓝色
+'文本'.yellow  // 黄色
+'文本'.red     // 红色
+'文本'.cyan    // 青色
+'文本'.gray    // 灰色
+'文本'.bold    // 加粗
+```
+
+## UI 排版规范
+
+### 动态对齐
+
+```javascript
+// 计算最大长度
+const maxLen = Math.max(...items.map(i => i.name.length), 4);
+
+// 使用 padEnd 对齐
+items.forEach(item => {
+    const name = item.name.padEnd(maxLen);
+    console.log(`  ${name}  ${item.description}`);
+});
+```
+
+### 分隔线
+
+```javascript
+console.log('─'.repeat(50).gray);
+```
+
+### 视觉层级
+
+```javascript
+console.log('');           // 空行分隔区块
+Ec.info('=== 标题 ===');   // 区块标题
+console.log('');
+// 内容...
+console.log('');
+```
+
+## 开发心得与避坑指南
+
+### readline 回显问题
+
+**问题：** 输入显示两次
+
+**原因：** 同时使用多个 readline 实例，或 raw mode 与普通 readline 混用
+
+**解决：**
+1. 使用本技能提供的 `scripts/menu.js`，它正确处理了 raw mode
+2. 菜单选择和确认输入分离：菜单完成后才使用 `Ec.ask`
+3. 不要在 raw mode 中调用 `Ec.ask`
+
+### raw mode 管理
+
+**问题：** 程序退出后终端异常
+
+**原因：** 未正确退出 raw mode
+
+**解决：**
+```javascript
+// 所有退出路径都要恢复
+process.stdin.setRawMode(false);
+process.stdin.removeListener('keypress', onKeypress);
+```
+
+### 异步流程问题
+
+**问题：** setTimeout 中的 async 函数未被等待
+
+**原因：** Promise 未正确链接
+
+**解决：** 使用独立的 async 函数，而不是在 Promise 回调中嵌套 async
+
+```javascript
+// 错误
+setTimeout(async () => {
+    const answer = await Ec.ask('?');
+    resolve(answer);  // resolve 可能在 await 之前执行
+}, 100);
+
+// 正确：分离成两个函数
+const menuResult = await selectMenu(items);  // 菜单
+const answer = await Ec.ask('确认？');       // 确认
+```
+
+### 参数解析限制
+
+**问题：** `Ec.parseArgument` 不支持可选值参数
+
+**解决：** 自行解析 `process.argv`
+
+```javascript
+const parseOptionalArg = (flagName, aliasName) => {
+    const args = process.argv.slice(3);
+    let hasFlag = false;
+    let value = null;
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === `-${aliasName}` || args[i] === `--${flagName}`) {
+            hasFlag = true;
+            const next = args[i + 1];
+            if (next && !next.startsWith('-')) {
+                value = next;
+            }
+            break;
+        }
+    }
+
+    return { hasFlag, value };
+};
+```
+
+### 资源清理
+
+**问题：** 临时文件未清理
+
+**解决：** 使用 try/finally
+
+```javascript
+let tempDir = null;
+try {
+    tempDir = createTempDir('task');
+    // 操作...
+} finally {
+    if (tempDir) {
+        await cleanup(tempDir);
+    }
+}
+```
+
+## 脚本引用
+
+本技能提供以下可复用的脚本模块：
+
+| 脚本 | 说明 | 文档 |
+|------|------|------|
+| `scripts/menu.js` | 交互式菜单 | [menu-api.md](menu-api.md) |
+| `scripts/file-utils.js` | 文件操作工具 | [file-utils-api.md](file-utils-api.md) |
+| `scripts/yaml-parser.js` | YAML 解析器 | [file-utils-api.md](file-utils-api.md) |
+
+**使用方式：**
+
+1. **复制到项目中使用**（推荐）
+   ```bash
+   cp -r skills/r2mo-rad-lain/scripts src/_scripts
+   ```
+
+2. **直接引用**（开发阶段）
+   ```javascript
+   const { selectMultiple } = require('../../skills/r2mo-rad-lain/scripts/menu');
+   ```
+
+## 注册执行器
+
+在 `src/executor/index.js` 中添加：
+
+```javascript
+const executeMyCommand = require('./executeMyCommand');
+
+const exported = {
+    // ... 其他执行器
+    executeMyCommand
+};
+module.exports = exported;
+```
+
+## 测试命令
+
+```bash
+# 运行命令
+node src/momo.js mycommand
+
+# 带参数
+node src/momo.js mycommand -p value
+
+# 查看帮助
+node src/momo.js help -c mycommand
+```
+
+## 依赖说明
+
+本技能使用的依赖（项目已包含）：
+
+- **colors**: 终端颜色支持
+- **co**: 生成器函数执行
+- **commander**: 命令行框架（仅用于底层，执行器不直接使用）
+- **underscore**: 工具函数
+- **immutable**: 不可变数据结构

package/.claude/skills/r2mo-rad-lain/examples/argument-parsing.js

@@ -0,0 +1,154 @@
+/**
+ * 参数解析示例
+ * 演示如何处理复杂的命令行参数
+ */
+
+// ============================================================
+// 使用 Ec.parseArgument（标准方式）
+// ============================================================
+
+/**
+ * 标准参数解析
+ * 适用于 key-value 成对参数
+ * 
+ * 命令示例：momo cmd -n value --name value
+ */
+const standardParsing = (options) => {
+    const Ec = require('../epic');
+    const parsed = Ec.parseArgument(options);
+    
+    // 支持 --name 和 -n 两种形式
+    const name = parsed.name || parsed.n;
+    const type = parsed.type || parsed.t;
+    
+    return { name, type };
+};
+
+// ============================================================
+// 自定义参数解析（支持可选值）
+// ============================================================
+
+/**
+ * 解析可选值参数
+ * 适用于参数值可以省略的情况
+ * 
+ * 命令示例：
+ *   momo cmd -r           -> hasFlag: true, value: null
+ *   momo cmd -r value     -> hasFlag: true, value: 'value'
+ *   momo cmd              -> hasFlag: false, value: null
+ */
+const parseOptionalArg = (flagName, aliasName) => {
+    const args = process.argv.slice(3);
+    let hasFlag = false;
+    let value = null;
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === `-${aliasName}` || arg === `--${flagName}`) {
+            hasFlag = true;
+            // 检查下一个参数是否是值（不以 - 开头）
+            const nextArg = args[i + 1];
+            if (nextArg && !nextArg.startsWith('-')) {
+                value = nextArg;
+            }
+            break;
+        }
+    }
+
+    return { hasFlag, value };
+};
+
+// ============================================================
+// 布尔标志解析
+// ============================================================
+
+/**
+ * 解析布尔标志
+ * 
+ * 命令示例：
+ *   momo cmd --verbose    -> true
+ *   momo cmd -v           -> true
+ *   momo cmd              -> false
+ */
+const parseBooleanFlag = (flagName, aliasName) => {
+    const args = process.argv.slice(3);
+    return args.includes(`--${flagName}`) || args.includes(`-${aliasName}`);
+};
+
+// ============================================================
+// 位置参数解析
+// ============================================================
+
+/**
+ * 解析位置参数
+ * 
+ * 命令示例：
+ *   momo cmd arg1 arg2    -> ['arg1', 'arg2']
+ */
+const parsePositionalArgs = () => {
+    const args = process.argv.slice(3);
+    const positional = [];
+    
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            // 跳过 flag 和它的值
+            i += 2;
+        } else {
+            positional.push(arg);
+            i++;
+        }
+    }
+    
+    return positional;
+};
+
+// ============================================================
+// 完整示例
+// ============================================================
+
+/**
+ * 综合参数解析示例
+ * 
+ * 命令格式：momo mycommand [target] -n name -r [repo] --verbose
+ */
+const parseAllArgs = (options) => {
+    // 1. 标准参数
+    const Ec = require('../epic');
+    let parsed = {};
+    try {
+        parsed = Ec.parseArgument(options);
+    } catch (e) {
+        // 忽略缺少值的错误，手动处理
+    }
+
+    // 2. 可选值参数
+    const remote = parseOptionalArg('remote', 'r');
+
+    // 3. 布尔标志
+    const verbose = parseBooleanFlag('verbose', 'v');
+
+    // 4. 位置参数
+    const positional = parsePositionalArgs();
+    const target = positional[0] || '.';
+
+    return {
+        name: parsed.name || parsed.n,
+        remote: remote,
+        verbose: verbose,
+        target: target
+    };
+};
+
+// ============================================================
+// 导出
+// ============================================================
+
+module.exports = {
+    standardParsing,
+    parseOptionalArg,
+    parseBooleanFlag,
+    parsePositionalArgs,
+    parseAllArgs
+};