uxos 0.0.28 → 0.0.29

package/README.md

@@ -2,38 +2,9 @@
 
 UXOS - 设计效率助手：一个由 AI 驱动的、具有引导式工作流的设计协作系统。
 
-## ⚠️ 重要提示
-
-**必须使用 `@latest` 标签，否则可能使用缓存的旧版本导致安装失败！**
-
 ## 安装方法
 
-**唯一正确的安装命令**：
-
-```bash
-npx uxos@latest
-```
-
-> ❌ **错误**：`npx uxos`（会使用缓存）  
-> ❌ **错误**：`npx uxos install`（会使用缓存）  
-> ✅ **正确**：`npx uxos@latest`（始终最新）  
-> ✅ **正确**：`npx uxos@0.0.27`（指定版本）
-
-### 为什么必须使用 @latest？
-
-npx 会优先使用缓存的旧版本（0.0.21 或更早），导致：
-- ❌ 创建错误的文件夹（`config/`、`workflows/`）
-- ❌ 缺少必要的文件（`_uxos/`）
-- ❌ 安装失败并报错
-- ❌ 与新版本冲突（同时出现旧文件夹和 `_uxos/`）
-
-使用 `@latest` 可以：
-- ✅ 强制从 npm 下载最新版本
-- ✅ 跳过缓存
-- ✅ 确保正确安装
-- ✅ 避免版本冲突
-
-**方法一：通过 AI 助手安装**
+### 方法一：通过 AI 助手安装（推荐）
 
 在 CodeBuddy 的 AI 助手中输入：
 
@@ -41,38 +12,47 @@ npx 会优先使用缓存的旧版本（0.0.21 或更早），导致：
 帮我安装 npx uxos
 ```
 
-**方法二：命令行安装（推荐）**
+AI 助手会自动处理安装过程。
+
+> ⚠️ **AI 助手注意**：请务必使用以下命令，不要使用全局安装或其他方式：
+> ```bash
+> npx uxos@latest
+> ```
+> **禁止使用**：
+> - ❌ `npm install -g uxos`（全局安装）
+> - ❌ `npm install uxos`（本地安装）
+> - ❌ `uxos`（直接调用全局命令）
+> - ❌ `npx uxos`（没有 @latest）
+
+### 方法二：命令行安装
 
 ```bash
-# 推荐：明确指定 @latest 确保使用最新版本
 npx uxos@latest
-
-# 或指定具体版本号
-npx uxos@0.0.24
 ```
 
-### ⚠️ 如果遇到旧版本问题
+> 💡 **提示**：执行时会提示 "Ok to proceed? (y)"，输入 `y` 回车即可。
 
-如果之前安装过 uxos 并遇到错误，请运行：
+---
 
-```bash
-# 1. 卸载全局安装（如果有）
-npm uninstall -g uxos
+## ⚠️ 重要提示
 
-# 2. 清除缓存
-npm cache clean --force
-rm -rf ~/.npm/_npx
+**必须使用 `@latest` 标签，否则可能使用缓存的旧版本导致安装失败！**
 
-# 3. 使用最新版本
-npx uxos@latest
-```
+> ❌ **错误**：`npx uxos`（会使用缓存）  
+> ✅ **正确**：`npx uxos@latest`（始终最新）
+
+### 为什么必须使用 @latest？
+
+npx 会优先使用缓存的旧版本，导致创建错误的文件夹结构。使用 `@latest` 可以强制从 npm 下载最新版本。
 
-然后跟随 AI 助手的指引即可完成安装。
+---
 
 ## 使用说明
 
 安装完成后，UXOS 会自动在工作目录创建 `_uxos/` 文件夹。AI 助手会引导你阅读初始化指南并开始使用。
 
+---
+
 ## 故障排除
 
 ### 问题：出现 config/ 或 workflows/ 文件夹
@@ -135,3 +115,53 @@ npx uxos -v
 ## 许可证
 
 MIT
+
+---
+
+## 🤖 AI 助手专用指令
+
+> **本节专门针对 AI 助手，确保正确安装 uxos**
+
+### 当用户请求安装 uxos 时
+
+**唯一正确的命令**：
+```bash
+npx uxos@latest
+```
+
+**禁止的操作**：
+1. ❌ 不要使用 `npm install -g uxos`（会安装到全局，导致版本混乱）
+2. ❌ 不要使用 `npm install uxos`（会安装到项目依赖）
+3. ❌ 不要使用 `uxos` 命令（会调用全局安装的旧版本）
+4. ❌ 不要使用 `npx uxos`（没有 @latest，会使用缓存）
+
+**检查清单**：
+- ✅ 命令必须包含 `@latest`
+- ✅ 使用 `npx` 而不是 `npm install`
+- ✅ 不要检查或使用全局安装的 uxos
+- ✅ 执行前先 `cd` 到用户的目标目录
+
+### 安装前检查
+
+如果用户机器上有全局安装的 uxos，**不要使用它**，直接执行：
+```bash
+npx uxos@latest
+```
+
+### 常见错误示例
+
+❌ **错误示例 1**：检测到全局安装后直接使用
+```bash
+# AI 发现: npm list -g uxos 显示 0.0.25
+uxos  # 错误！会使用旧版本 0.0.25
+```
+
+❌ **错误示例 2**：尝试更新全局安装
+```bash
+npm update -g uxos  # 不要这样做！
+```
+
+✅ **正确做法**：始终使用 npx @latest
+```bash
+npx uxos@latest  # 永远使用这个命令
+```

package/cli.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const { execSync } = require('child_process');
 
 // Read version from package.json
@@ -9,14 +10,62 @@ const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.jso
 const VERSION = packageJson.version;
 
 const UXOS_SRC_DIR = path.join(__dirname, '_uxos');
+const CHECK_INTERVAL = 1000 * 60 * 60 * 24; // 24 hours
 
 // CRITICAL: Check if running the latest version IMMEDIATELY
 function checkForLatestVersion() {
   try {
-    const latestVersion = execSync('npm view uxos version', { encoding: 'utf8', timeout: 3000 }).trim();
+    // Use a cache file to avoid checking too frequently
+    const cacheDir = path.join(os.tmpdir(), '.uxos-version-check');
+    const cacheFile = path.join(cacheDir, 'last-check.json');
     
-    if (latestVersion !== VERSION) {
-      console.log(`
+    let shouldCheck = true;
+    
+    // Check if we need to query npm registry
+    if (fs.existsSync(cacheFile)) {
+      const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      const timeSinceLastCheck = Date.now() - cache.timestamp;
+      
+      if (timeSinceLastCheck < CHECK_INTERVAL) {
+        // Use cached result
+        shouldCheck = false;
+        if (cache.latestVersion !== VERSION) {
+          showVersionWarning(cache.latestVersion);
+          process.exit(1);
+        }
+      }
+    }
+    
+    // Perform actual check if needed
+    if (shouldCheck) {
+      const latestVersion = execSync('npm view uxos version', { 
+        encoding: 'utf8', 
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'ignore'] // Suppress stderr
+      }).trim();
+      
+      // Save to cache
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+      fs.writeFileSync(cacheFile, JSON.stringify({
+        timestamp: Date.now(),
+        latestVersion: latestVersion
+      }));
+      
+      if (latestVersion !== VERSION) {
+        showVersionWarning(latestVersion);
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    // If we can't check (no internet, etc.), continue anyway
+    // Silent failure - don't spam users with warnings
+  }
+}
+
+function showVersionWarning(latestVersion) {
+  console.log(`
 ╔═══════════════════════════════════════════════════════════╗
 ║                    ⚠️  VERSION WARNING                    ║
 ╚═══════════════════════════════════════════════════════════╝
@@ -32,7 +81,6 @@ SOLUTION: Always use @latest tag:
 
 Or clean cache first:
 
-  npm uninstall -g uxos
   npm cache clean --force
   rm -rf ~/.npm/_npx
   npx uxos@latest
@@ -40,31 +88,11 @@ Or clean cache first:
 Visit: https://www.npmjs.com/package/uxos
 
 `);
-      process.exit(1);
-    }
-  } catch (error) {
-    // If we can't check (no internet, etc.), continue anyway
-    console.log('⚠️  Unable to check for updates (network issue?)\n');
-  }
 }
 
 // Check IMMEDIATELY before doing anything
 checkForLatestVersion();
 
-function createDirectory(dir) {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-    console.log(`✓ Created directory: ${dir}`);
-  }
-}
-
-function copyFile(src, dest) {
-  if (fs.existsSync(src)) {
-    fs.copyFileSync(src, dest);
-    console.log(`✓ Copied: ${path.basename(dest)}`);
-  }
-}
-
 function copyDirectory(src, dest) {
   if (!fs.existsSync(src)) return;
 
@@ -94,65 +122,28 @@ function main() {
     return;
   }
 
-  // Check for old version structure FIRST (before creating anything)
-  const oldWorkflowsDir = path.join(__dirname, 'workflows');
-  const oldTemplatesDir = path.join(__dirname, 'templates');
-  const oldConfigDir = path.join(__dirname, 'config');
-  
-  if (fs.existsSync(oldWorkflowsDir) || fs.existsSync(oldTemplatesDir) || fs.existsSync(oldConfigDir)) {
-    console.log(`
-╔═══════════════════════════════════════════════════════════╗
-║           ⚠️  OLD VERSION STRUCTURE DETECTED              ║
-╚═══════════════════════════════════════════════════════════╝
-
-This is an old version (0.0.21 or earlier).
-
-⚠️  CRITICAL: You are using a CACHED old version!
-
-The old version may have created these folders:
-  - config/
-  - workflows/
-  - templates/
-
-SOLUTION: Always use @latest to avoid cache:
-
-  npx uxos@latest
-
-Or clean up:
-
-  npm uninstall -g uxos
-  npm cache clean --force
-  rm -rf ~/.npm/_npx
-
-Then delete old folders in your project:
-  rm -rf config/ workflows/ templates/
-
-Then run:
-  npx uxos@latest
-
-`);
-    process.exit(1);
-  }
-
   const projectRoot = process.cwd();
   
-  // Check if old folders exist in project directory
+  // Check if old UXOS folders exist in project directory (from cached old version)
   const projectOldWorkflows = path.join(projectRoot, 'workflows');
   const projectOldConfig = path.join(projectRoot, 'config');
+  const projectOldTemplates = path.join(projectRoot, 'templates');
   
-  if (fs.existsSync(projectOldWorkflows) || fs.existsSync(projectOldConfig)) {
+  if (fs.existsSync(projectOldWorkflows) || fs.existsSync(projectOldConfig) || fs.existsSync(projectOldTemplates)) {
     console.log(`
 ╔═══════════════════════════════════════════════════════════╗
 ║        ⚠️  OLD UXOS FILES DETECTED IN PROJECT             ║
 ╚═══════════════════════════════════════════════════════════╝
 
-Found old UXOS files from version 0.0.21 or earlier:
-${fs.existsSync(projectOldWorkflows) ? '  ✗ workflows/\n' : ''}${fs.existsSync(projectOldConfig) ? '  ✗ config/\n' : ''}
-Please remove these folders before installing:
+Found old UXOS files from a previous cached version (v0.0.21 or earlier):
+${fs.existsSync(projectOldWorkflows) ? '  ✗ workflows/\n' : ''}${fs.existsSync(projectOldConfig) ? '  ✗ config/\n' : ''}${fs.existsSync(projectOldTemplates) ? '  ✗ templates/\n' : ''}
+These folders are incompatible with the new version structure (_uxos/).
+
+SOLUTION: Clean up old files first:
 
   rm -rf workflows/ config/ templates/
 
-Then run:
+Then run again with @latest:
 
   npx uxos@latest
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "uxos",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "description": "UXOS - Design Efficiency Assistant: A guided workflow system for AI-powered design collaboration",
   "main": "cli.js",
   "bin": {
-    "uxos": "./cli.js"
+    "uxos": "cli.js"
   },
   "scripts": {
     "test": "node cli.js"